MCP — verbinding met Claude / Cursor

De AstroWay MCP-server exposeert alle 723 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 · npm: npmjs.com/package/@astroway/mcp · hosted: 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 (10 000 credits/maand gratis).

Klik op de knop — Cursor opent zich, vraagt om bevestiging en voegt de server automatisch toe:

Installeren in Cursor →

Zonder JSON te bewerken. In elke Claude Desktop-chat:

Klik op de + links van het invoerveld → kies in het menu “Add connector”.
Kies in het dialoogvenster “Add custom connector”.
Naam: astroway-hosted
URL: https://mcp.astroway.info/mcp
Vouw “Advanced settings” uit → voeg in “Custom headers” toe:
- Key: Authorization
- Value: Bearer aw_live_... (je sleutel)
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:

{
  "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

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:

{
  "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. Incidenten van meer dan 5 minuten worden gepost als postmortem binnen 5 werkdagen (volgens /sla/).

Stdio (npm) — voor lokale ontwikkeling

De @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). 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/<path> 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) — 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:

{
  "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:

{
  "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:

{
  "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:

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/<version> (Node/<node-version>)
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:

{
  "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_<group>_<tool> 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:

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
mcpservers.org: wacht op goedkeuring (per mei 2026)
awesome-mcp-servers (punkpeye): PR #5972