NatalAI MCP documentation

Connect your AI agent to professional astrology calculations via Model Context Protocol (MCP).

1. Get an API key

1. Sign in to NatalAI and open Cabinet → MCP API keys.
2. Click “Generate API key”, name your bot, and copy the key immediately.
3. The full key is shown only once. Store it securely.

2. Endpoint

MCP JSON-RPC endpoint (Streamable HTTP):

https://natalai.io/mcp/v1/

Tool manifest (no key required): https://natalai.io/mcp/v1/schema/

3. Authentication

Two options: (1) API key via X-API-Key or Authorization: Bearer your-key; (2) OAuth 2.1 — the client discovers metadata at /.well-known/openid-configuration, you sign in on NatalAI and approve access. OAuth access tokens are also sent as Authorization: Bearer.

4. Perplexity

Custom connector — OAuth (recommended)

1. Open Perplexity → Add custom connector.
2. Server URL: https://natalai.io/mcp/v1/
3. Authentication: OAuth.
4. Transport: Streaming HTTP.
5. Complete login on NatalAI and click Allow on the consent screen.

Custom connector — API key

1. Open Perplexity → Add custom connector (or Connectors / MCP).
2. Server URL: https://natalai.io/mcp/v1/
3. Authentication: API key — paste your NatalAI MCP key (raw value, no “Bearer ” prefix).
4. Transport: Streaming HTTP (Streamable HTTP).
5. Network access: Public.
6. Accept the risk notice and click Add.

NatalAI accepts the key as Authorization: Bearer …, which is what Perplexity sends for API-key connectors. If the connector was created after OAuth was enabled and keeps prompting OAuth, remove it and add again with Authentication: API key.

Agent API

Pass the NatalAI key in the MCP tool’s authorization field (raw token). Perplexity will send it to our server as Bearer.

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Build a natal chart for 1991-04-26 10:30 in Minsk using NatalAI.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "natalai",
        "server_url": "https://natalai.io/mcp/v1/",
        "authorization": "YOUR_NATALAI_API_KEY"
      }
    ]
  }'

5. OpenAI (Responses API)

Use a remote MCP tool in the OpenAI Responses API. Put the NatalAI key in authorization (raw token).

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "input": "Build a natal chart for 1991-04-26 10:30 in Minsk using NatalAI.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "natalai",
        "server_description": "Western and Vedic astrology calculations",
        "server_url": "https://natalai.io/mcp/v1/",
        "authorization": "YOUR_NATALAI_API_KEY",
        "require_approval": "never"
      }
    ]
  }'

ChatGPT web connectors support OAuth against our authorization server (/.well-known/openid-configuration). Perplexity Agent API does not run the OAuth UI flow — use the connector UI or pass a token/key in authorization.

6. Claude Desktop

{
  "mcpServers": {
    "natalai": {
      "url": "https://natalai.io/mcp/v1/",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

7. Cursor / Windsurf

{
  "mcp": {
    "servers": [
      {
        "name": "NatalAI",
        "url": "https://natalai.io/mcp/v1/",
        "headers": { "X-API-Key": "YOUR_API_KEY" }
      }
    ]
  }
}

8. curl example

curl -X POST https://natalai.io/mcp/v1/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "natal_chart",
      "arguments": {
        "birth_date": "1991-04-26",
        "birth_time": "10:30",
        "latitude": 53.9,
        "longitude": 27.57,
        "timezone": "Europe/Minsk",
        "gender": "male"
      }
    }
  }'

9. JSON-RPC methods

10. Available tools

• natal_chart
• ephemeris_day
• transits
• transit_strength
• progressions
• solar_return
• synastry
• vedic_natal
• aspect_patterns

11. Limits

Default rate limits per key: 60 requests/minute, 1000 requests/day. Keys can be deactivated in the cabinet at any time.

← Back to MCP overview