# MCP — підключення Claude / Cursor Model Context Protocol сервер AstroWay експонує **усі {siteMeta.endpoints} ендпоінтів** як інструменти для 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](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · hosted: [mcp.astroway.info/health](https://mcp.astroway.info/health) ## Hosted (`mcp.astroway.info`) — zero install Швидкий старт без npm — обери свій клієнт. Перед установкою візьми ключ на [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 кредитів/міс безкоштовно). Натисни кнопку — Cursor відкриється, попросить підтвердити, додасть запис автоматично: Install in Cursor → :::caution[Обов'язковий 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](https://api.astroway.info/dashboard/keys). 4. Збережи → знов відкрий список MCP → переконайся що статус **enabled** + зелена точка + лічильник `630 tools enabled`. Альтернативно — відредагуй файл напряму: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Без редагування 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 ресурсами. Для Cline / Continue / Windsurf або старих версій Claude Desktop / Cursor: ```json { "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 → відкрити заново). ### Перевірка ```bash 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`: ```json { "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](https://status.astroway.info). Інциденти > 5 хвилин публікуємо як postmortem протягом 5 робочих днів (per [/sla/](/sla/)). ## Stdio (npm) — для локальної розробки [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — npm-пакет, який запускається локально як subprocess. Один npm-пакет, нативна інтеграція з Claude Desktop, Cursor та будь-яким MCP-сумісним клієнтом. ## Як це працює Tool list генерується **на момент білда** з live OpenAPI-spec ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Кожен реліз пакета автоматично підхоплює усі нові ендпоінти — нічого вручну підтримувати не треба. Кожен ендпоінт стає інструментом виду: - `tools/list` повертає опис та схему вводу (з прикладом тіла запиту) - `tools/call` робить HTTP POST на `https://api.astroway.info/v1/` із вашим `ASTROWAY_API_KEY` - Відповідь повертається агенту як structured JSON Кожен реліз ще й ship'иться з SLSA provenance ([Sigstore-attested](https://search.sigstore.dev/)) — це гарантія що npm-пакет збудований саме з commit'у в публічному репо. ## Встановлення ### Claude Desktop (macOS) Додай у `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Перезапусти Claude Desktop. У бару під чатом з'явиться 🛠️ індикатор з кількістю завантажених tool-ів. ### Cursor Додай у `~/.cursor/mcp.json`: ```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-сумісному клієнті. Конфіг ідентичний — змінюється лише шлях до файлу: ```json { "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-сервер: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Privacy — з v1.0.0+ Цей MCP-сервер **не відправляє нічого назад до AstroWay** окрім самих API-викликів які ти йому даєш виконати. Жодної телеметрії, жодного analytics, жодного opt-in/opt-out перемикача — тиша за замовчуванням. Вихідні запити несуть два ідентифікаційні заголовки щоб AstroWay backend міг розрізняти MCP-трафік від прямого HTTP у власних логах: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Жоден з них не містить session ID, machine fingerprint чи будь-чого персонального. Це стандартна `User-Agent` семантика — кожен CLI-інструмент шле подібну інформацію. ## Subset registration — з v1.0.0+ Якщо використовуєш лише частину каталогу — реєструй підмножину щоб контекстне вікно LLM залишалося компактним: ```jsonc { "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__` не буде перейменоване чи видалене всередині `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-інструменти. Або з командного рядка: ```bash 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](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** очікує approval (на момент травня 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Посилання - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 API docs: [/docs/api/](/docs/api/) - 🔑 Sign up: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Pricing: [/pricing/](/pricing/) - 🌐 Public repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)