MCP — підключення Claude / Cursor

Model Context Protocol сервер AstroWay експонує усі 722 ендпоінтів як інструменти для AI-агента. Два режими — обидва підтримуються нативно усіма MCP-сумісними клієнтами.

Режим	URL / команда	Коли вибирати
Hosted HTTP	https://mcp.astroway.info/mcp	Claude Web (claude.ai в браузері), Claude Desktop / Cursor / Code newcomers без npm, або коли хочеш zero-install
Stdio (npm)	npx @astroway/mcp	Cursor power users, локальна розробка, privacy-conscious (ключ ніколи не залишає твою машину), offline-ready

Hosted endpoint і npm-пакет використовують той самий каталог інструментів (генерується з одного /v1/openapi.json). Auth: однаковий aw_test_* / aw_live_* API-ключ — у hosted надсилається через Authorization: Bearer … header, у stdio — через ASTROWAY_API_KEY env var.

Source: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) — zero install

Швидкий старт без npm — обери свій клієнт. Перед установкою візьми ключ на api.astroway.info/dashboard/sign-up (10 000 кредитів/міс безкоштовно).

Cursor (one-click)

Натисни кнопку — Cursor відкриється, попросить підтвердити, додасть запис автоматично:

Install in Cursor →

Обов’язковий 2-й крок — інакше не запрацює

Cursor не вміє підставляти секрет із deeplink — у ~/.cursor/mcp.json запишеться літерал Bearer YOUR_API_KEY, на який сервер відповідає 403 invalid_format.

Після кліку кнопки:

1. Cursor Settings (⚙️ верхній правий кут) → Tools & MCP → знайди astroway-hosted у списку.
2. Натисни три крапки (⋯) поряд із сервером → Edit configuration.
3. У полі Authorization заміни Bearer YOUR_API_KEY на Bearer aw_test_… (або aw_live_…) — твій реальний ключ із Dashboard.
4. Збережи → знов відкрий список MCP → переконайся що статус enabled + зелена точка + лічильник 630 tools enabled.

Альтернативно — відредагуй файл напряму: ~/.cursor/mcp.json (headers.Authorization).

Заувага

Cursor накладає ліміт на довжину імен: server_name:tool_name ≤ 60 символів. Близько 50 з 630 інструментів (групи hellenistic_brennan_*, psychological_modern_*, numerology_kabbalistic_strict_*) фільтруються Cursor-ом і будуть недоступні через LLM. Інші ~580 працюють. У Claude Desktop такого ліміту немає — повний каталог.

Claude Desktop (UI flow)

Без редагування JSON. У будь-якому чаті Claude Desktop:

1. Натисни + ліворуч від поля вводу → у меню обери “Add connector”.
2. У діалозі обери “Add custom connector”.
3. Name: astroway-hosted
4. URL: https://mcp.astroway.info/mcp
5. Розгорни “Advanced settings” → у “Custom headers” додай:
   • Key: Authorization
   • Value: Bearer aw_live_... (твій ключ)
6. Add → знайди astroway-hosted у списку Connectors, увімкни перемикач.

Перезавантажувати Claude Desktop не потрібно. Натисни + у новому чаті — в Connectors з’явиться astroway-hosted з усіма 630 інструментами + 12 промптами + 14 ресурсами.

JSON config (manual)

Для Cline / Continue / Windsurf або старих версій Claude Desktop / Cursor:

{
  "mcpServers": {
    "astroway-hosted": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": {
        "Authorization": "Bearer aw_live_..."
      }
    }
  }
}

Шляхи до конфігів:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json (глобально) або .cursor/mcp.json (у workspace)
• Cline (VS Code): .cline/mcp.json у workspace
• Continue: ~/.continue/config.json (блок mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Після правки повністю перезапусти клієнт (Cmd+Q → відкрити заново).

Перевірка

curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}

У клієнті — попроси: “List 5 AstroWay tool names from astroway-hosted”. Має повернути імена типу astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full, …

Rate limits

Hosted endpoint захищений 3-рівневим обмеженням: Cloudflare DDoS-шар + nginx 120 req/min/IP + in-memory bucket 60/60s/(IP+key). Реальні MCP-клієнти (Claude Desktop, Cursor) не наближаються до цих лімітів — вони не роблять burst-запитів. Якщо твоя автоматизація / CI потребує > 120 req/min — використовуй stdio режим (там лімітів немає, ходить напряму через api.astroway.info/v1/* з твоїм тарифним rate-limit’ом).

Що якщо mcp.astroway.info тимчасово недоступний

Якщо hosted endpoint повертає 5xx, MCP-клієнт побачить помилку при tools/list. Це не впливає на stdio-клієнтів — вони запускають локальний npm-пакет, який ходить напряму до api.astroway.info/v1/* без проміжного hosted-шару.

Fallback для критичних інтеграцій: додай другий MCP-сервер в конфіг із stdio-режимом — клієнт автоматично використає його, якщо hosted не відповідає на tools/list:

{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    },
    "astroway-fallback": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Реальний uptime hosted endpoint видно на status.astroway.info. Інциденти > 5 хвилин публікуємо як postmortem протягом 5 робочих днів (per /sla/).

Stdio (npm) — для локальної розробки

@astroway/mcp — npm-пакет, який запускається локально як subprocess. Один npm-пакет, нативна інтеграція з Claude Desktop, Cursor та будь-яким MCP-сумісним клієнтом.

Як це працює

Tool list генерується на момент білда з live OpenAPI-spec (api.astroway.info/v1/openapi.json). Кожен реліз пакета автоматично підхоплює усі нові ендпоінти — нічого вручну підтримувати не треба.

Кожен ендпоінт стає інструментом виду:

• tools/list повертає опис та схему вводу (з прикладом тіла запиту)
• tools/call робить HTTP POST на https://api.astroway.info/v1/<path> із вашим ASTROWAY_API_KEY
• Відповідь повертається агенту як structured JSON

Кожен реліз ще й ship’иться з SLSA provenance (Sigstore-attested) — це гарантія що npm-пакет збудований саме з commit’у в публічному репо.

Встановлення

Claude Desktop (macOS)

Додай у ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_..."
      }
    }
  }
}

Перезапусти Claude Desktop. У бару під чатом з’явиться 🛠️ індикатор з кількістю завантажених tool-ів.

Cursor

Додай у ~/.cursor/mcp.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Cline / Continue / Windsurf / Copilot / VS Code MCP

Та сама npx @astroway/mcp команда працює в кожному MCP-сумісному клієнті. Конфіг ідентичний — змінюється лише шлях до файлу:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Клієнт	Шлях до конфіга
Cline (VS Code)	.cline/mcp.json у корені workspace
Continue	~/.continue/config.json (під mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	preview-флаг → mcp.json у workspace
VS Code MCP extension	~/.vscode/mcp.json

Інші MCP клієнти

Запусти як stdio-сервер:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Порада

Отримати ключ — на api.astroway.info/dashboard/sign-up. Free tier — 10 000 кредитів/місяць, без картки.

Privacy — з v1.0.0+

Цей MCP-сервер не відправляє нічого назад до AstroWay окрім самих API-викликів які ти йому даєш виконати. Жодної телеметрії, жодного analytics, жодного opt-in/opt-out перемикача — тиша за замовчуванням.

Вихідні запити несуть два ідентифікаційні заголовки щоб AstroWay backend міг розрізняти MCP-трафік від прямого HTTP у власних логах:

• User-Agent: astroway-mcp/<version> (Node/<node-version>)
• X-Astroway-Channel: mcp

Жоден з них не містить session ID, machine fingerprint чи будь-чого персонального. Це стандартна User-Agent семантика — кожен CLI-інструмент шле подібну інформацію.

Subset registration — з v1.0.0+

Якщо використовуєш лише частину каталогу — реєструй підмножину щоб контекстне вікно LLM залишалося компактним:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // лише ці префікси
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, тратять кредити)
  }
}

Поширені групи: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Запусти npx @astroway/mcp --list-tools щоб побачити повний набір.

ASTROWAY_READONLY=1 пропускає три групи що внутрішньо викликають LLM (ai, horoscope, reports) — корисно коли хочеш чисту детерміновану математику карт без витрат кредитів на генерацію тексту.

Stability commitment — з v1.0.0+

• Каталог заморожений на час сесії. 624 tools, 12 prompts, 14 resources вшиті в опублікований npm-пакет на момент білду — нічого не змінюється під час підключення. Якщо твій клієнт кешує tools/list після першого виклику — він залишається коректним для всієї сесії.
• Tool identifiers стабільні в межах major версії. Імʼя під astroway_<group>_<tool> не буде перейменоване чи видалене всередині v1.x без deprecation note в CHANGELOG.md та одно-minor парралельної доступності.
• Tool input shape стабільний в межах minor версії. Затягування (regex, range, enum) приходить у патчах; додавання обовʼязкового поля вимагає minor bump.
• Refresh каталогу — переустановкою. npm i -g @astroway/mcp@latest (або npx -y @astroway/mcp форма у твоєму конфізі) підтягує поточний набір при наступному старті.

Приклади промптів

Після підключення сервера попроси AI:

Натальна карта

Розрахуй мою натальну карту — народжений 15 березня 1990, 14:30, Київ. Опиши Сонце, Місяць, Асцендент і знайди тісні аспекти.

Claude викличе chart tool з твоїми параметрами, отримає структурований JSON, і опише карту словами.

Транзити

Які значущі транзити повільних планет припадуть на мою натал-карту впродовж 2027 року?

Claude робить два tool-call’и: спочатку transits (поточний знімок), потім transit-calendar (діапазон). Інтерпретує тренди.

Vedic Mahadasha

Запусти Vimshottari Mahadasha для людини, народженої 22.07.1985 06:45 у Мумбаї. У якому періоді ця людина зараз?

Через vedic/dashas/vimshottari/maha tool — точний UTC-timestamp поточного періоду.

Synastry

Порівняй дві карти: А — 10.06.1988 09:15 Лондон, Б — 22.11.1991 22:40 Берлін. Які найсильніші крос-аспекти?

synastry tool з двома chart блоками + інтерпретація балу сумісності.

Tarot

Витягни 3 карти Rider-Waite-Smith: Минуле — Теперішнє — Майбутнє. Питання: «чи варто прийняти нову роботу?». Seed = 42.

tarot/rider-waite/spread з фіксованим seed для відтворюваності.

Список усіх tool-ів

Після підключення спитай у Claude:

Перерахуй усі astroway-інструменти.

Або з командного рядка:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (запускає stdio-сервер; протокольні tool-list виклики йдуть від MCP клієнта)

Конфігурація

Змінна	За замовчуванням	Опис	З версії
ASTROWAY_API_KEY	(обовʼязково)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Override для self-hosted/staging-середовищ.	0.1.0
ASTROWAY_TOOL_GROUPS	(всі групи)	Comma-separated префікси для обмеження каталогу (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 пропускає LLM-backed групи (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug — рівень логування на stderr.	0.8.0
LOG_FILE	(не пишеться)	Шлях до файлу для дублювання логів.	0.8.0
MCP_FLAT_TOOLS	0	1 повертає pre-v0.9 flat-імена (chart замість astroway_western_chart). Legacy.	0.9.0

Чому MCP, а не пряма інтеграція

Generic LLM (без grounding) скаже «десь у липні Сатурн утворить тригон до твого Юпітера» — без точної дати, з ±15 днів дрифтом. MCP-агент робить tool_use POST /v1/transits і повертає UTC-timestamp до секунди, на справжньому Swiss Ephemeris.

Перевага не в LLM, а в гарантії що математика реальна — не вигадана.

Дистрибуція пакета

• mcp.so listing: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: очікує approval (на момент травня 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Посилання

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 API docs: /docs/api/
• 🔑 Sign up: /dashboard/sign-up
• 💰 Pricing: /pricing/
• 🌐 Public repo (MIT): github.com/astroway/astroway-mcp