Документация NatalAI MCP

Подключите ИИ-агента к профессиональным астрологическим расчётам через Model Context Protocol (MCP).

1. Получите API-ключ

1. Войдите в NatalAI и откройте Кабинет → MCP API-ключи.
2. Нажмите «Сгенерировать API-ключ», назовите бота и сразу скопируйте ключ.
3. Полный ключ показывается только один раз. Храните его в безопасном месте.

2. Endpoint

MCP JSON-RPC endpoint (Streamable HTTP):

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

Манифест инструментов (без ключа): https://natalai.io/mcp/v1/schema/

3. Аутентификация

Два варианта: (1) API-ключ через X-API-Key или Authorization: Bearer ваш-ключ; (2) OAuth 2.1 — клиент получает метаданные по адресу /.well-known/openid-configuration, вы авторизуетесь в NatalAI и разрешаете доступ. Access-токены OAuth также передаются через Authorization: Bearer.

4. Perplexity

Пользовательский коннектор — OAuth (рекомендуется)

1. Откройте Perplexity → Add custom connector.
2. URL сервера: https://natalai.io/mcp/v1/
3. Аутентификация: OAuth.
4. Транспорт: Streaming HTTP.
5. Пройдите авторизацию на NatalAI и нажмите Allow (Разрешить) на экране согласия.

Пользовательский коннектор — API-ключ

1. Откройте Perplexity → Add custom connector (или Connectors / MCP).
2. URL сервера: https://natalai.io/mcp/v1/
3. Аутентификация: API-ключ — вставьте ваш ключ NatalAI MCP (само значение, без префикса «Bearer »).
4. Транспорт: Streaming HTTP (Streamable HTTP).
5. Сетевой доступ: Public.
6. Примите уведомление о рисках и нажмите Add.

NatalAI принимает ключ как Authorization: Bearer …, именно так Perplexity отправляет его для коннекторов по API-ключу. Если коннектор был создан после включения OAuth и постоянно запрашивает OAuth, удалите его и добавьте снова с типом аутентификации API-ключ.

Agent API

Передайте ключ NatalAI в поле authorization MCP-инструмента (чистый токен). Perplexity отправит его на наш сервер как 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)

Используйте удаленный MCP-инструмент в OpenAI Responses API. Поместите ключ NatalAI в поле authorization (чистый токен).

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 поддерживают OAuth через наш сервер авторизации (/.well-known/openid-configuration). Agent API Perplexity не запускает процесс OAuth через UI — используйте интерфейс коннектора или передайте токен/ключ в поле 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

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

10. Доступные инструменты

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

11. Лимиты

Лимиты по умолчанию на ключ: 60 запросов/мин, 1000 запросов/день. Ключи можно деактивировать в кабинете в любой момент.

← К обзору MCP