MCP - połączenie Claude / Cursor

Model Context Protocol serwer AstroWay eksponuje wszystkie 771 endpointów jako narzędzia dla agenta AI. Dwa tryby – oba są natywnie obsługiwane przez wszystkie klienci zgodni 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 newcomers bez npm, albo kiedy chcesz zero-install
Stdio (npm)	npx @astroway/mcp	Cursor power users, lokalny rozwój, privacy-conscious (klucz nigdy nie opuszcza twojego komputera), offline-ready

Hosted endpoint i pakiet npm używają tej samej katalogu narzędzi (generowany z jednego /v1/openapi.json). Auth: taki sam aw_test_* / aw_live_* API‑key – w hosted jest wysyłany przez nagłówek Authorization: Bearer …, w 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 instalacji

Szybki start bez npm – wybierz swojego klienta. Przed instalacją weź klucz na api.astroway.info/dashboard/sign-up (10 000 kredytów/miesiąc za darmo).

Cursor (one-click)

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

Zainstaluj w Cursorze →

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

Cursor nie potrafi podstawić sekretu z deeplink – w ~/.cursor/mcp.json zapisze się literał Bearer YOUR_API_KEY, na co serwer odpowiada 403 invalid_format.

Po kliknięciu przycisku:

1. Cursor Settings (⚙️ w prawym górnym rogu) → Tools & MCP → znajdź astroway-hosted na liście.
2. Kliknij trzy kropki (⋯) obok serwera → Edit configuration.
3. W polu Authorization zamień Bearer YOUR_API_KEY na Bearer aw_test_… (lub aw_live_…) – twój rzeczywisty klucz z Dashboard.
4. Zapisz → ponownie otwórz listę MCP → upewnij się, że status enabled + zielona kropka + licznik 780+ 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 90 z 780+ narzędzi (głównie grupy hellenistic_*, psychological_*, zi_wei_*, zodiac_* i numerology_*) jest filtrowanych przez Cursor i będzie niedostępnych przez LLM. Pozostałe ~690 działają. W Claude Desktop takiego limitu nie ma – pełny katalog.

Claude Desktop

Settings → Developer → Edit Config otwiera claude_desktop_config.json. Ten plik uruchamia tylko lokalne komendy: zapis z samym url jest pomijany z komunikatem “Some MCP servers couldn’t be loaded”. Hosted‑serwer łączy się przez most mcp-remote, wymaga Node.js:

{
  "mcpServers": {
    "astroway-hosted": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.astroway.info/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer aw_live_..." }
    }
  }
}

Całkowicie zamknij Claude Desktop (Cmd+Q) i otwórz ponownie. Klucz leży w env, ponieważ Claude Desktop na Windows rozdziela argument po spacji po Bearer.

Dialog Add custom connector w Settings → Connectors przyjmuje tylko nazwę i URL, nie ma pola na nagłówek Authorization, więc klucz AstroWay nie może być teraz przez to przekazany.

JSON config (manual)

Dla Cursor, Cline, Continue i Windsurf, które przyjmują zdalny url bezpośrednio:

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

Ścieżki do konfiguracji:

• Cursor: ~/.cursor/mcp.json (globalnie) lub .cursor/mcp.json (w workspace)
• Cline (VS Code): .cline/mcp.json w workspace
• Continue: ~/.continue/config.json (sekcja mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

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

Sprawdzenie

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

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

Limity zapytań

Hosted endpoint jest chroniony 3‑poziomowym ograniczeniem: warstwa Cloudflare DDoS + edge proxy 120 req/min/IP + in‑memory bucket 60/60s/(IP+key). Rzeczywiste klienci MCP (Claude Desktop, Cursor) nie zbliżają się do tych limitów – nie wykonują burst‑zapytó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 taryfowym rate‑limitem).

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

Jeśli hosted endpoint zwróci 5xx, klient MCP zobaczy błąd przy tools/list. To nie wpływa na klientów stdio – uruchamiają lokalny pakiet npm, który łączy się 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 (per /sla/).

Stdio (npm) – dla lokalnego rozwoju

@astroway/mcp – pakiet npm, który uruchamia się lokalnie jako subprocess. Jeden pakiet npm, natywna integracja z Claude Desktop, Cursor i dowolnym klientem zgodnym z MCP.

Jak to działa

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

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

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

Każde wydanie jest także ship’owane z SLSA provenance (Sigstore-attested) – to gwarancja, że pakiet npm został zbudowany dokładnie z commita w publicznym repo.

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. Na pasku pod czatem pojawi się 🛠️ wskaźnik 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 kliencie 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 korzeniu workspace
Continue	~/.continue/config.json (pod mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	preview‑flaga → mcp.json w workspace
VS Code MCP extension	~/.vscode/mcp.json

Inne klienci MCP

Uruchom jako serwer stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Wskazówka

Uzyskaj klucz – na api.astroway.info/dashboard/sign-up. Free tier – 10 000 kredytów/miesiąc, bez karty.

Prywatność - od v1.0.0+

Ten serwer MCP nie wysyła nic z powrotem do AstroWay poza samymi wywołaniami API, które mu przekazujesz. Zero telemetry, zero analytics, zero przełącznika opt‑in/opt‑out – cisza domyślnie.

Zapytania wyjściowe niosą dwa identyfikacyjne nagłówki, aby backend AstroWay mógł rozróżnić ruch MCP od bezpośredniego HTTP w własnych logach:

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

Żaden z nich nie zawiera session ID, odcisku maszyny ani żadnych danych osobowych. To standardowa semantyka User-Agent – każdy CLI‑narzędzie wysyła podobne informacje.

Rejestracja podzbioru - od v1.0.0+

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

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // only these prefixes
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, costs credits)
  }
}

Popularne grupy: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), 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 zużywania kredytów na generowanie tekstu.

Zobowiązanie stabilności - od v1.0.0+

• Katalog zamrożony na czas sesji. 780+ narzędzi, 12 promptów, 14 zasobów wbudowanych w opublikowany pakiet npm w momencie builda – nic się nie zmienia podczas połączenia. Jeśli twój klient buforuje tools/list po pierwszym wywołaniu – pozostaje poprawny przez całą sesję.
• Identyfikatory narzędzi są stabilne w ramach wersji major. Nazwa w formacie astroway_<group>_<tool> nie zostanie przemianowana ani usunięta w v1.x bez notatki o deprecjacji w CHANGELOG.md i jednoczesnej dostępności w wersji minor.
• Kształt wejścia narzędzia jest stabilny w ramach wersji minor. Rozszerzenia (regex, range, enum) przychodzą w patchach; dodanie wymaganego pola wymaga bumpa minor.
• Odświeżanie katalogu: reinstalacja. npm i -g @astroway/mcp@latest (lub npx -y @astroway/mcp w twojej konfiguracji) pobiera aktualny zestaw przy następnym starcie.

Przykłady promptów

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ź bliskie aspekty.

Tranzyty

Jakie znaczące tranzyty wolnych planet przypadają na moją kartę natalną w ciągu 2027 roku?

Vedic Mahadasha

Uruchom Vimshottari Mahadasha dla osoby urodzonej 22.07.1985 06:45 w Mumbaju. W którym okresie ta osoba jest teraz?

Synastry

Porównaj dwie karty: A – 10.06.1988 09:15 Londyn, B – 22.11.1991 22:40 Berlin. Jakie są najsilniejsze cross‑aspekty?

Tarot

Wyciągnij 3 karty Rider‑Waite‑Smith: Przeszłość – Teraźniejszość – Przyszłość. Pytanie: “czy warto przyjąć nową pracę?”. Seed = 42.

Lista wszystkich narzędzi

Po podłączeniu zapytaj Claude:

Wymień wszystkie narzędzia astroway.

Albo z wiersza poleceń:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (starts the stdio server; tool-list calls come from the MCP client over the protocol)

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	Override dla środowisk self‑hosted/staging.	0.1.0
ASTROWAY_TOOL_GROUPS	(wszystkie grupy)	Przedrostki oddzielone przecinkami do ograniczenia katalogu (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 pomija grupy wspierane przez LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug – poziom logowania na stderr.	0.8.0
LOG_FILE	(nie zapisywany)	Ścieżka do pliku dla duplikacji logów.	0.8.0
MCP_FLAT_TOOLS	0	1 zwraca pre‑v0.9 płaskie nazwy (chart zamiast astroway_western_chart). Legacy.	0.9.0

Dlaczego MCP, a nie bezpośrednia integracja

Generic LLM (bez grounding) powie “gdzieś w lipcu Saturn utworzy trygon do twojego Jowisza” – bez dokładnej daty, z odchyleniem ±15 dni. Agent MCP wykonuje tool_use POST /v1/transits i zwraca UTC‑timestamp do sekundy, na prawdziwym Swiss Ephemeris.

Zaleta nie leży 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 (na maj 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Linki

• 📦 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