# MCP — verbinding met Claude / Cursor De AstroWay MCP-server exposeert **alle {siteMeta.endpoints} endpoints** als tools voor een AI-agent. Er zijn twee modi — beide worden native ondersteund door alle MCP-compatibele clients. | Modus | URL / commando | Wanneer kiezen | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai in de browser), Claude Desktop / Cursor / Code voor beginners zonder npm, of wanneer je zero-install wilt | | **Stdio (npm)** | `npx @astroway/mcp` | Cursor power users, lokale ontwikkeling, privacy-gevoelig (de sleutel verlaat nooit je machine), offline-ready | De hosted endpoint en de npm-pakket gebruiken **dezelfde toolcatalogus** (gegenereerd uit één `/v1/openapi.json`). Authenticatie: dezelfde `aw_test_*` / `aw_live_*` API-sleutel — bij hosted wordt deze verzonden via de `Authorization: Bearer …` header, bij stdio via de `ASTROWAY_API_KEY` omgevingsvariabele. Bron: [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 Snelle start zonder npm — kies je client. Voordat je installeert, haal je een sleutel op via [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 credits/maand gratis). Klik op de knop — Cursor opent zich, vraagt om bevestiging en voegt de server automatisch toe: Installeren in Cursor → :::caution[Verplichte 2e stap — anders werkt het niet] Cursor kan de geheimen niet vervangen in de deeplink — in `~/.cursor/mcp.json` wordt de letterlijke tekst `Bearer YOUR_API_KEY` geschreven, waar de server op reageert met `403 invalid_format`. **Na het klikken op de knop:** 1. **Cursor Instellingen** (⚙️ rechtsboven) → **Tools & MCP** → zoek `astroway-hosted` in de lijst. 2. Klik op de drie puntjes (`⋯`) naast de server → **Bewerken configuratie**. 3. Vervang in het veld `Authorization` de tekst `Bearer YOUR_API_KEY` door `Bearer aw_test_…` (of `aw_live_…`) — je echte sleutel uit het [Dashboard](https://api.astroway.info/dashboard/keys). 4. Sla op → open de MCP-lijst opnieuw en controleer dat de status **ingeschakeld** is + groene punt + teller `630 tools enabled`. Alternatief: bewerk het bestand direct: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Zonder JSON te bewerken. In elke Claude Desktop-chat: 1. Klik op de **`+`** links van het invoerveld → kies in het menu **"Add connector"**. 2. Kies in het dialoogvenster **"Add custom connector"**. 3. **Naam:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Vouw **"Advanced settings"** uit → voeg in **"Custom headers"** toe: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (je sleutel) 6. **Add** → zoek `astroway-hosted` in de lijst Connectors, schakel de schakelaar in. Herstart Claude Desktop **niet** nodig. Klik op `+` in een nieuwe chat — in Connectors verschijnt `astroway-hosted` met alle 630 tools + 12 prompts + 14 resources. Voor Cline / Continue / Windsurf of oudere versies van Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Paden naar de configuratiebestanden: - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json` - **Cursor:** `~/.cursor/mcp.json` (globale instelling) of `.cursor/mcp.json` (per workspace) - **Cline (VS Code):** `.cline/mcp.json` in de workspace - **Continue:** `~/.continue/config.json` (onder `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Na het bewerken volledig herstarten van de client (Cmd+Q → opnieuw openen). ### Controle ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` In de client — vraag: *"List 5 AstroWay tool names from astroway-hosted"*. Dit moet namen retourneren zoals `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Rate limits De hosted endpoint is beschermd met een 3-laagse beperking: Cloudflare DDoS-laag + nginx `120 req/min/IP` + in-memory bucket `60/60s/(IP+key)`. Echte MCP-clients (Claude Desktop, Cursor) komen niet in de buurt van deze limieten — ze maken geen burst-verzoeken. Als je automatisering / CI meer dan 120 req/min nodig heeft — gebruik dan de **stdio**-modus (daar zijn geen limieten, deze gaat rechtstreeks via `api.astroway.info/v1/*` met je tariefplan-rate-limit). ### Wat als `mcp.astroway.info` tijdelijk niet beschikbaar is Als de hosted endpoint 5xx retourneert, ziet de MCP-client een fout bij `tools/list`. Dit **heeft geen invloed** op stdio-clients — deze starten de lokale npm-pakket op, dat rechtstreeks naar `api.astroway.info/v1/*` gaat zonder tussenlaag. **Fallback voor kritieke integraties:** voeg een **tweede MCP-server** toe in de configuratie in stdio-modus — de client gebruikt deze automatisch als de hosted niet reageert op `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_..." } } } } ``` De echte uptime van de hosted endpoint is te zien op [status.astroway.info](https://status.astroway.info). Incidenten van meer dan 5 minuten worden gepost als postmortem binnen 5 werkdagen (volgens [/sla/](/sla/)). ## Stdio (npm) — voor lokale ontwikkeling De [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) is een npm-pakket dat lokaal als subprocess wordt uitgevoerd. Één npm-pakket, native integratie met Claude Desktop, Cursor en elke MCP-compatibele client. ## Hoe het werkt De toollijst wordt **op build-tijd** gegenereerd uit de live OpenAPI-specificatie ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Elke release van het pakket pakt automatisch alle nieuwe endpoints op — je hoeft niets handmatig te onderhouden. Elk endpoint wordt een tool van de vorm: - `tools/list` retourneert de beschrijving en het invoerschema (met voorbeeld van het verzoeklichaam) - `tools/call` maakt een HTTP POST naar `https://api.astroway.info/v1/` met je `ASTROWAY_API_KEY` - Het antwoord wordt aan de agent teruggegeven als gestructureerde JSON Elke release wordt ook geleverd met SLSA-provenance ([Sigstore-geattesteerd](https://search.sigstore.dev/)) — dit garandeert dat het npm-pakket precies is gebouwd vanaf de commit in de publieke repo. ## Installatie ### Claude Desktop (macOS) Voeg toe aan `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Herstart Claude Desktop. In de balk onder de chat verschijnt een 🛠️-icoon met het aantal geladen tools. ### Cursor Voeg toe aan `~/.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 Het zelfde `npx @astroway/mcp`-commando werkt in elke MCP-compatibele client. De configuratie is identiek — alleen het pad naar het bestand verandert: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Client | Pad naar configuratie | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` in de root van de workspace | | **Continue** | `~/.continue/config.json` (onder `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | preview-vlag → `mcp.json` in de workspace | | **VS Code MCP-extensie** | `~/.vscode/mcp.json` | ### Andere MCP-clients Start op als stdio-server: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Privacy — vanaf v1.0.0+ Deze MCP-server **stuurt niets terug naar AstroWay** behalve de API-verzoeken die je hem laat uitvoeren. Geen telemetrie, geen analytics, geen opt-in/opt-out-schakelaar — stilte is standaard. Uitgaande verzoeken bevatten twee identificatie-headers zodat de AstroWay-backend MCP-verkeer kan onderscheiden van directe HTTP-verzoeken in eigen logs: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Geen van beide bevat een sessie-ID, machine-fingerprint of iets persoonlijks. Dit is standaard `User-Agent`-semantiek — elke CLI-tool stuurt dergelijke informatie. ## Subset-registratie — vanaf v1.0.0+ Als je slechts een deel van de catalogus gebruikt — registreer dan een subset om ervoor te zorgen dat het contextvenster van de LLM compact blijft: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // alleen deze prefixen "ASTROWAY_READONLY": "1" // sla ai/horoscope/reports over (LLM-backed, verbruiken credits) } } ``` Veelvoorkomende groepen: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastrie/composiet/Davison), `prognostics` (transits/progressies/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Voer `npx @astroway/mcp --list-tools` uit om de volledige set te zien. `ASTROWAY_READONLY=1` slaat drie groepen over die intern de LLM aanroepen (`ai`, `horoscope`, `reports`) — handig wanneer je pure, deterministische kaartberekeningen wilt zonder credits te verbruiken voor tekstgeneratie. ## Stabiliteitsgarantie — vanaf v1.0.0+ - **De catalogus is bevroren tijdens de sessie.** 624 tools, 12 prompts, 14 resources zijn ingebouwd in het gepubliceerde npm-pakket op het moment van de build — er verandert niets tijdens de verbinding. Als je client `tools/list` na de eerste aanroep cachet, blijft deze gedurende de hele sessie correct. - **Tool-identifiers zijn stabiel binnen een major-versie.** De naam onder `astroway__` wordt niet hernoemd of verwijderd binnen `v1.x` zonder een deprecation-notitie in `CHANGELOG.md` en parallelle beschikbaarheid in minstens één minor-versie. - **De invoervorm van tools is stabiel binnen een minor-versie.** Regex, bereik, enum worden in patches toegevoegd; het toevoegen van een verplicht veld vereist een minor bump. - **Vernieuwen van de catalogus:** door opnieuw te installeren. `npm i -g @astroway/mcp@latest` (of de `npx -y @astroway/mcp`-vorm in je configuratie) haalt de huidige set op bij de volgende start. ## Voorbeeldprompts Na het aansluiten van de server vraag je de AI: ### Natal chart > Bereken mijn natal chart — geboren op 15 maart 1990, 14:30, Kiev. Beschrijf Zon, Maan, Ascendant en zoek nauwe aspecten. Claude roept het `chart`-tool aan met je parameters, ontvangt gestructureerde JSON en beschrijft de chart in woorden. ### Transits > Welke significante transits van langzame planeten zullen in 2027 op mijn natal chart vallen? Claude maakt twee tool-aanroepen: eerst `transits` (huidige snapshot), dan `transit-calendar` (bereik). Interpreteert de trends. ### Vedic Mahadasha > Start Vimshottari Mahadasha voor iemand geboren op 22.07.1985 06:45 in Mumbai. In welke periode bevindt deze persoon zich nu? Via het `vedic/dashas/vimshottari/maha`-tool — exacte UTC-timestamp van de huidige periode. ### Synastry > Vergelijk twee charts: A — 10.06.1988 09:15 Londen, B — 22.11.1991 22:40 Berlijn. Wat zijn de sterkste cross-aspecten? Het `synastry`-tool met twee `chart`-blokken + interpretatie van de compatibiliescore. ### Tarot > Trek 3 Rider-Waite-Smith kaarten: Verleden — Heden — Toekomst. Vraag: «moet ik de nieuwe baan accepteren?». Seed = 42. `tarot/rider-waite/spread` met vaste seed voor reproduceerbaarheid. ## Lijst van alle tools Na aansluiten vraag je aan Claude: > Geef alle astroway-tools weer. Of vanuit de commandoregel: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (start de stdio-server; protocolmatige tool-list-aanroepen worden gedaan door de MCP-client) ``` ## Configuratie | Variabele | Standaard | Beschrijving | Vanaf versie | |---|---|---|---| | `ASTROWAY_API_KEY` | *(verplicht)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Override voor self-hosted/staging-omgevingen. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(alle groepen)* | Komma-gescheiden prefixen om de catalogus te beperken (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` slaat LLM-backed groepen over (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — logniveau naar stderr. | 0.8.0 | | `LOG_FILE` | *(niet geschreven)* | Pad naar bestand voor duplicatie van logs. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` retourneert pre-v0.9 flat-namen (`chart` in plaats van `astroway_western_chart`). Legacy. | 0.9.0 | ## Waarom MCP en geen directe integratie Een generieke LLM (zonder grounding) zegt *«ergens in juli zal Saturnus een driehoek vormen met je Jupiter»* — zonder exacte datum, met een drift van ±15 dagen. De **MCP-agent** maakt `tool_use POST /v1/transits` en retourneert een UTC-timestamp **tot op de seconde**, op basis van Swiss Ephemeris. Het voordeel zit niet in de LLM, maar in de **garantie dat de wiskunde klopt** — niet verzonnen. ## Distributie van het pakket - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** wacht op goedkeuring (per mei 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Links - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 API-docs: [/docs/api/](/docs/api/) - 🔑 Registreren: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Prijzen: [/pricing/](/pricing/) - 🌐 Publieke repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)