MCP — połączenie Claude / Cursor

Serwer AstroWay w Model Context Protocol (MCP) udostępnia wszystkie 723 endpointy jako narzędzia dla AI-agenta. Obsługiwane są dwa tryby — oba są natywnie wspierane przez wszystkie klienty zgodne z MCP.

Tryb	URL / komenda	Kiedy wybrać
Hosted HTTP	https://mcp.astroway.info/mcp	Claude Web (claude.ai w przeglądarce), Claude Desktop / Cursor / Code dla nowicjuszy bez npm, lub gdy chcesz zero-install
Stdio (npm)	npx @astroway/mcp	Zaawansowani użytkownicy Cursor, lokalny rozwój, dbający o prywatność (klucz nigdy nie opuszcza twojego komputera), gotowy do pracy offline

Hosted endpoint i pakiet npm używają tej samej listy narzędzi (generowanej z jednego /v1/openapi.json). Autoryzacja: ten sam klucz API aw_test_* / aw_live_* — w trybie hosted wysyłany przez nagłówek Authorization: Bearer …, w trybie stdio przez zmienną środowiskową ASTROWAY_API_KEY.

Źródło: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) — zero install

Szybki start bez npm — wybierz swój klient. Przed instalacją pobierz klucz na api.astroway.info/dashboard/sign-up (10 000 darmowych kredytów/miesiąc).

Cursor (one-click)

Kliknij przycisk — Cursor otworzy się, poprosi o potwierdzenie, automatycznie doda wpis:

Zainstaluj w Cursor →

Obowiązkowy 2. krok — inaczej nie zadziała

Cursor nie potrafi podmieniać sekretów z deeplink — w ~/.cursor/mcp.json zapisze się dosłowny tekst Bearer YOUR_API_KEY, na który serwer odpowie 403 invalid_format.

Po kliknięciu przycisku:

1. Cursor Settings (⚙️ prawy górny róg) → Tools & MCP → znajdź astroway-hosted na liście.
2. Kliknij trzy kropki (⋯) obok serwera → Edit configuration.
3. W polu Authorization zastąp Bearer YOUR_API_KEY na Bearer aw_test_… (lub aw_live_…) — twoim rzeczywistym kluczem z Dashboard.
4. Zapisz → ponownie otwórz listę MCP → upewnij się, że status to enabled + zielony punkt + licznik 630 tools enabled.

Alternatywnie edytuj plik bezpośrednio: ~/.cursor/mcp.json (headers.Authorization).

Notatka

Cursor nakłada limit na długość nazw: server_name:tool_name ≤ 60 znaków. Około 50 z 630 narzędzi (grupy hellenistic_brennan_*, psychological_modern_*, numerology_kabbalistic_strict_*) jest filtrowanych przez Cursor i będzie niedostępnych przez LLM. Pozostałe ~580 działają. W Claude Desktop nie ma takiego limitu — pełny katalog.

Claude Desktop (UI flow)

Bez edycji JSON. W dowolnym czacie Claude Desktop:

1. Kliknij + po lewej stronie pola wprowadzania → w menu wybierz “Add connector”.
2. W oknie dialogowym wybierz “Add custom connector”.
3. Name: astroway-hosted
4. URL: https://mcp.astroway.info/mcp
5. Rozwiń “Advanced settings” → w “Custom headers” dodaj:
   • Key: Authorization
   • Value: Bearer aw_live_... (twój klucz)
6. Add → znajdź astroway-hosted na liście Connectors, włącz przełącznik.

Nie musisz restartować Claude Desktop. Kliknij + w nowym czacie — w Connectors pojawi się astroway-hosted z wszystkimi 630 narzędziami + 12 promptów + 14 zasobów.

JSON config (manual)

Dla Cline / Continue / Windsurf lub starszych wersji Claude Desktop / Cursor:

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

Ścieżki do plików konfiguracyjnych:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json (globalnie) lub .cursor/mcp.json (w przestrzeni roboczej)
• Cline (VS Code): .cline/mcp.json w przestrzeni roboczej
• Continue: ~/.continue/config.json (blok mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Po edycji całkowicie uruchom klienta ponownie (Cmd+Q → otwórz ponownie).

Weryfikacja

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

W klientach — poproś: “List 5 AstroWay tool names from astroway-hosted”. Powinno zwrócić nazwy typu astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full, …

Limity szybkości

Hosted endpoint jest chroniony 3-poziomowym ograniczeniem: Cloudflare DDoS + nginx 120 req/min/IP + in-memory bucket 60/60s/(IP+key). Rzeczywiste klienty MCP (Claude Desktop, Cursor) nie zbliżają się do tych limitów — nie wykonują burst-requestów. Jeśli twoja automatyzacja / CI potrzebuje > 120 req/min — użyj trybu stdio (tam nie ma limitów, działa bezpośrednio przez api.astroway.info/v1/* z twoim limitem taryfowym).

Co jeśli mcp.astroway.info jest tymczasowo niedostępny

Jeśli hosted endpoint zwraca 5xx, klient MCP zobaczy błąd przy tools/list. To nie wpływa na klientów stdio — uruchamiają lokalny pakiet npm, który działa bezpośrednio z api.astroway.info/v1/* bez pośredniej warstwy hosted.

Fallback dla krytycznych integracji: dodaj drugi serwer MCP w konfiguracji w trybie stdio — klient automatycznie użyje go, jeśli hosted nie odpowie na 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_..." }
    }
  }
}

Rzeczywisty uptime hosted endpoint widać na status.astroway.info. Incydenty > 5 minut publikujemy jako postmortem w ciągu 5 dni roboczych (zgodnie z /sla/).

Stdio (npm) — dla lokalnego rozwoju

@astroway/mcp — pakiet npm uruchamiany lokalnie jako subprocess. Jeden pakiet npm, natywna integracja z Claude Desktop, Cursor i każdym klientem zgodnym z MCP.

Jak to działa

Lista narzędzi jest generowana w momencie budowania z live OpenAPI-spec (api.astroway.info/v1/openapi.json). Każde wydanie pakietu automatycznie przechwytuje wszystkie nowe endpointy — nie musisz niczego utrzymywać ręcznie.

Każdy endpoint staje się narzędziem postaci:

• tools/list zwraca opis i schemat wejścia (z przykładem ciała żądania)
• tools/call wykonuje HTTP POST na https://api.astroway.info/v1/<path> z twoim ASTROWAY_API_KEY
• Odpowiedź jest zwracana agentowi jako ustrukturyzowany JSON

Każde wydanie jest również dostarczane z SLSA provenance (attestowane przez Sigstore) — to gwarancja, że pakiet npm został zbudowany z konkretnego commita w publicznym repozytorium.

Instalacja

Claude Desktop (macOS)

Dodaj do ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Uruchom ponownie Claude Desktop. W pasku pod czatem pojawi się ikona 🛠️ z liczbą załadowanych narzędzi.

Cursor

Dodaj do ~/.cursor/mcp.json:

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

Cline / Continue / Windsurf / Copilot / VS Code MCP

Ta sama komenda npx @astroway/mcp działa w każdym klientem zgodnym z MCP. Konfiguracja jest identyczna — zmienia się tylko ścieżka do pliku:

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

Klient	Ścieżka do konfiguracji
Cline (VS Code)	.cline/mcp.json w głównym katalogu przestrzeni roboczej
Continue	~/.continue/config.json (w bloku mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	flaga preview → mcp.json w przestrzeni roboczej
VS Code MCP extension	~/.vscode/mcp.json

Inne klienty MCP

Uruchom jako serwer stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Wskazówka

Pobierz klucz — na api.astroway.info/dashboard/sign-up. Darmowy tier — 10 000 kredytów/miesiąc, bez karty.

Prywatność — od v1.0.0+

Ten serwer MCP nie wysyła niczego z powrotem do AstroWay poza samymi wywołaniami API, które mu zlecasz. Brak telemetrii, brak analytics, brak przełącznika opt-in/opt-out — cisza domyślnie.

Wychodzące żądania zawierają dwa identyfikujące nagłówki, aby backend AstroWay mógł rozróżnić ruch MCP od bezpośredniego HTTP w swoich logach:

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

Żaden z nich nie zawiera identyfikatora sesji, odcisku maszyny ani niczego osobistego. To standardowa semantyka User-Agent — każde narzędzie CLI wysyła podobne informacje.

Rejestracja podzbioru — od v1.0.0+

Jeśli używasz tylko części katalogu — zarejestruj podzbiór, aby okno kontekstowe LLM pozostało kompaktowe:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // tylko te prefiksy
    "ASTROWAY_READONLY": "1"                               // pomiń grupy ai/horoscope/reports (obsługiwane przez LLM, zużywają kredyty)
  }
}

Popularne grupy: western, vedic, tarot, numerology, hd (Human Design), relational (synastria/kompozyt/Davison), prognostics (transity/progresje/rewolucje), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Uruchom npx @astroway/mcp --list-tools, aby zobaczyć pełny zestaw.

ASTROWAY_READONLY=1 pomija trzy grupy, które wewnętrznie wywołują LLM (ai, horoscope, reports) — przydatne, gdy chcesz czystą, deterministyczną matematykę kart bez wydawania kredytów na generowanie tekstu.

Gwarancja stabilności — od v1.0.0+

• Katalog jest zamrożony na czas sesji. 624 narzędzi, 12 promptów, 14 zasobów jest wbudowanych w opublikowany pakiet npm w momencie budowania — nic się nie zmienia podczas połączenia. Jeśli twój klient cache’uje tools/list po pierwszym wywołaniu, pozostaje poprawny przez całą sesję.
• Identyfikatory narzędzi są stabilne w obrębie wersji major. Nazwa pod astroway_<group>_<tool> nie zostanie zmieniona ani usunięta wewnątrz v1.x bez notki o deprecacji w CHANGELOG.md i jednoczesnej dostępności w minorze.
• Kształt wejścia narzędzia jest stabilny w obrębie wersji minor. Zmiany wciągnięć (regex, zakres, enum) pojawiają się w patchach; dodanie obowiązkowego pola wymaga bumpu minor.
• Odświeżanie katalogu — przez reinstalację. npm i -g @astroway/mcp@latest (lub npx -y @astroway/mcp w twojej konfiguracji) pobiera aktualny zestaw przy następnym uruchomieniu.

Przykładowe prompty

Po podłączeniu serwera poproś AI:

Karta natalna

Oblicz moją kartę natalną — urodzony 15 marca 1990, 14:30, Kijów. Opisz Słońce, Księżyc, Ascendent i znajdź mocne aspekty.

Claude wywoła narzędzie chart z twoimi parametrami, otrzyma ustrukturyzowany JSON i opisze kartę słownie.

Tranzyty

Jakie znaczące tranzyty wolnych planet będą miały miejsce w mojej karcie natalnej w 2027 roku?

Claude wykonuje dwa wywołania narzędzi: najpierw transits (aktualny snapshot), potem transit-calendar (zakres). Interpretuje trendy.

Vedic Mahadasha

Uruchom Vimshottari Mahadasha dla osoby urodzonej 22.07.1985 06:45 w Bombaju. W jakim okresie ta osoba jest teraz?

Poprzez narzędzie vedic/dashas/vimshottari/maha — dokładny znacznik czasu UTC bieżącego okresu.

Synastria

Porównaj dwie karty: A — 10.06.1988 09:15 Londyn, B — 22.11.1991 22:40 Berlin. Jakie są najsilniejsze krzyżowe aspekty?

Narzędzie synastry z dwoma blokami chart + interpretacja wyniku.

Tarot

Wyciągnij 3 karty Rider-Waite-Smith: Przeszłość — Teraźniejszość — Przyszłość. Pytanie: «czy powinienem przyjąć nową pracę?». Seed = 42.

Narzędzie tarot/rider-waite/spread z ustalonym seedem dla powtarzalności.

Lista wszystkich narzędzi

Po podłączeniu zapytaj Claude:

Wymień wszystkie narzędzia AstroWay.

Lub z wiersza poleceń:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (uruchamia serwer stdio; wywołania narzędzi list są wykonywane przez klienta MCP)

Konfiguracja

Zmienna	Domyślnie	Opis	Od wersji
ASTROWAY_API_KEY	(wymagane)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Przesłonięcie dla self-hosted/staging środowisk.	0.1.0
ASTROWAY_TOOL_GROUPS	(wszystkie grupy)	Oddzielone przecinkami prefiksy do ograniczenia katalogu (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 pomija grupy obsługiwane przez LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug — poziom logowania do stderr.	0.8.0
LOG_FILE	(nie zapisywany)	Ścieżka do pliku dla duplikowania logów.	0.8.0
MCP_FLAT_TOOLS	0	1 zwraca stare nazwy flat z przed v0.9 (chart zamiast astroway_western_chart). Legacy.	0.9.0

Dlaczego MCP, a nie bezpośrednia integracja

Ogólny LLM (bez grounding) powie «gdzieś w lipcu Saturn utworzy trójkąt do twojego Jowisza» — bez dokładnej daty, z dryfem ±15 dni. Agent MCP wykonuje tool_use POST /v1/transits i zwraca znacznik czasu UTC do sekundy, na prawdziwym Swiss Ephemeris.

Zaleta nie tkwi w LLM, ale w gwarancji, że matematyka jest rzeczywista — nie wymyślona.

Dystrybucja pakietu

• mcp.so listing: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: oczekuje na zatwierdzenie (stan na maj 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Linki

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