MCP — connessione Claude / Cursor

Il server Model Context Protocol di AstroWay espone tutti gli 723 endpoint come strumenti per agenti AI. Sono supportati due modalità — entrambe native per qualsiasi client MCP compatibile.

Modalità	URL / comando	Quando sceglierla
Hosted HTTP	https://mcp.astroway.info/mcp	Claude Web (claude.ai nel browser), Claude Desktop / Cursor / Code per principianti senza npm, o se vuoi zero-install
Stdio (npm)	npx @astroway/mcp	Power user di Cursor, sviluppo locale, privacy-conscious (la chiave non lascia mai la tua macchina), pronto per l’offline

L’endpoint hosted e il pacchetto npm utilizzano lo stesso catalogo di strumenti (generato da un unico /v1/openapi.json). Autenticazione: stessa chiave API aw_test_* / aw_live_* — nell’hosted viene inviata tramite header Authorization: Bearer …, nello stdio tramite variabile d’ambiente ASTROWAY_API_KEY.

Source: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) — zero install

Inizia subito senza npm — scegli il tuo client. Prima di installare, prendi la tua chiave su api.astroway.info/dashboard/sign-up (10 000 crediti/mese gratis).

Cursor (one-click)

Clicca il pulsante — Cursor si aprirà, ti chiederà di confermare e aggiungerà automaticamente la configurazione:

Installa in Cursor →

Passo 2 obbligatorio — altrimenti non funzionerà

Cursor non sostituisce i segreti nei deeplink — nel file ~/.cursor/mcp.json verrà scritto letteralmente Bearer YOUR_API_KEY, al quale il server risponde con 403 invalid_format.

Dopo aver cliccato il pulsante:

1. Cursor Settings (⚙️ in alto a destra) → Tools & MCP → trova astroway-hosted nella lista.
2. Clicca sui tre puntini (⋯) accanto al server → Edit configuration.
3. Nel campo Authorization sostituisci Bearer YOUR_API_KEY con Bearer aw_test_… (o aw_live_…) — la tua chiave reale da Dashboard.
4. Salva → riapri la lista MCP → assicurati che lo stato sia enabled con un punto verde e il conteggio 630 tools enabled.

In alternativa, modifica direttamente il file: ~/.cursor/mcp.json (headers.Authorization).

Nota

Cursor impone un limite di lunghezza ai nomi: server_name:tool_name ≤ 60 caratteri. Circa 50 dei 630 strumenti (gruppi hellenistic_brennan_*, psychological_modern_*, numerology_kabbalistic_strict_*) vengono filtrati da Cursor e saranno inaccessibili tramite LLM. Gli altri ~580 funzionano. In Claude Desktop questo limite non esiste — catalogo completo.

Claude Desktop (UI flow)

Nessuna modifica a JSON. In qualsiasi chat di Claude Desktop:

1. Clicca + a sinistra del campo di input → nel menu scegli “Add connector”.
2. Nel dialogo seleziona “Add custom connector”.
3. Name: astroway-hosted
4. URL: https://mcp.astroway.info/mcp
5. Espandi “Advanced settings” → in “Custom headers” aggiungi:
   • Key: Authorization
   • Value: Bearer aw_live_... (la tua chiave)
6. Add → trova astroway-hosted nella lista dei Connectors, attiva l’interruttore.

Non è necessario riavviare Claude Desktop. Clicca + in una nuova chat — nella lista dei Connectors apparirà astroway-hosted con tutti i 630 strumenti + 12 prompt + 14 risorse.

JSON config (manuale)

Per Cline / Continue / Windsurf o versioni vecchie di Claude Desktop / Cursor:

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

Percorsi dei file di configurazione:

• 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) o .cursor/mcp.json (nel workspace)
• Cline (VS Code): .cline/mcp.json nel workspace
• Continue: ~/.continue/config.json (blocco mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Dopo la modifica, riavvia completamente il client (Cmd+Q → riapri).

Verifica

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

Nel client — chiedi: “List 5 AstroWay tool names from astroway-hosted”. Dovrebbe restituire nomi come astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full, …

Rate limits

L’endpoint hosted è protetto da un sistema a tre livelli: Cloudflare DDoS layer + nginx 120 req/min/IP + bucket in-memory 60/60s/(IP+key). I client MCP reali (Claude Desktop, Cursor) non si avvicinano a questi limiti — non fanno richieste burst. Se la tua automazione / CI necessita di > 120 req/min — usa la modalità stdio (nessun limite, comunica direttamente con api.astroway.info/v1/* con il tuo rate-limit del piano tariffario).

Cosa succede se mcp.astroway.info è temporaneamente non disponibile

Se l’endpoint hosted restituisce 5xx, il client MCP vedrà un errore in tools/list. Questo non influisce sui client stdio — eseguono il pacchetto npm locale che si collega direttamente a api.astroway.info/v1/* senza uno strato intermedio hosted.

Fallback per integrazioni critiche: aggiungi un secondo server MCP nella configurazione in modalità stdio — il client lo userà automaticamente se l’hosted non risponde a 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_..." }
    }
  }
}

L’uptime reale dell’endpoint hosted è visibile su status.astroway.info. Incidenti superiori a 5 minuti vengono pubblicati come postmortem entro 5 giorni lavorativi (secondo /sla/).

Stdio (npm) — per lo sviluppo locale

@astroway/mcp è un pacchetto npm che viene eseguito localmente come subprocess. Un unico pacchetto npm, integrazione nativa con Claude Desktop, Cursor e qualsiasi client MCP compatibile.

Come funziona

La lista degli strumenti viene generata al momento del build dalla specifica OpenAPI live (api.astroway.info/v1/openapi.json). Ogni release del pacchetto include automaticamente tutti i nuovi endpoint — non serve mantenere nulla manualmente.

Ogni endpoint diventa uno strumento del tipo:

• tools/list restituisce descrizione e schema di input (con esempio del corpo della richiesta)
• tools/call esegue una POST HTTP su https://api.astroway.info/v1/<path> con la tua ASTROWAY_API_KEY
• La risposta viene restituita all’agente come JSON strutturato

Ogni release viene anche distribuita con la provenance SLSA (attestata da Sigstore) — garanzia che il pacchetto npm sia stato costruito dal commit pubblico nel repo.

Installazione

Claude Desktop (macOS)

Aggiungi in ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Riavvia Claude Desktop. Nella barra sotto la chat apparirà un’icona 🛠️ con il numero di strumenti caricati.

Cursor

Aggiungi in ~/.cursor/mcp.json:

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

Cline / Continue / Windsurf / Copilot / VS Code MCP

Lo stesso comando npx @astroway/mcp funziona in ogni client MCP compatibile. La configurazione è identica — cambia solo il percorso del file:

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

Client	Percorso del file di configurazione
Cline (VS Code)	.cline/mcp.json nella root del workspace
Continue	~/.continue/config.json (sotto mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	flag di anteprima → mcp.json nel workspace
VS Code MCP extension	~/.vscode/mcp.json

Altri client MCP

Esegui come server stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Consiglio

Per ottenere una chiave — api.astroway.info/dashboard/sign-up. Il piano gratuito offre 10 000 crediti/mese, senza carta di credito.

Privacy — da v1.0.0+

Questo server MCP non invia nulla indietro ad AstroWay oltre alle chiamate API che gli chiedi di eseguire. Nessuna telemetria, nessun analytics, nessun interruttore opt-in/opt-out — silenzio di default.

Le richieste in uscita includono due header di identificazione affinché il backend di AstroWay possa distinguere il traffico MCP da quello HTTP diretto nei propri log:

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

Nessuno di questi contiene session ID, fingerprint della macchina o altre informazioni personali. È la semantica standard di User-Agent — ogni strumento CLI invia informazioni simili.

Subset registration — da v1.0.0+

Se usi solo una parte del catalogo — registra un sottoinsieme per mantenere compatta la finestra di contesto dell’LLM:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // solo questi prefissi
    "ASTROWAY_READONLY": "1"                               // salta ai/horoscope/reports (LLM-backed, consumano crediti)
  }
}

Gruppi comuni: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transiti/progressioni/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Esegui npx @astroway/mcp --list-tools per vedere l’elenco completo.

ASTROWAY_READONLY=1 salta i tre gruppi che internamente chiamano LLM (ai, horoscope, reports) — utile quando vuoi solo matematica deterministica delle carte senza spendere crediti per generare testo.

Stability commitment — da v1.0.0+

• Catalogo congelato per sessione. 624 strumenti, 12 prompt, 14 risorse sono inclusi nel pacchetto npm pubblicato al momento del build — nulla cambia durante la connessione. Se il tuo client memorizza in cache tools/list dopo la prima chiamata, rimane corretto per tutta la sessione.
• Identificatori degli strumenti stabili entro la stessa major version. Il nome sotto astroway_<group>_<tool> non verrà rinominato o rimosso all’interno di v1.x senza una nota di deprecazione nel CHANGELOG.md e almeno una minor release parallela.
• Forma dell’input degli strumenti stabile entro la stessa minor version. Restrizioni (regex, range, enum) arrivano nei patch; l’aggiunta di un campo obbligatorio richiede un bump di minor.
• Aggiorna il catalogo reinstallando. npm i -g @astroway/mcp@latest (o la forma npx -y @astroway/mcp nel tuo file di configurazione) per ottenere l’insieme corrente al prossimo avvio.

Esempi di prompt

Dopo aver collegato il server chiedi all’AI:

Carta natale

Calcola la mia carta natale — nato il 15 marzo 1990, ore 14:30, Kiev. Descrivi Sole, Luna, Ascendente e trova gli aspetti stretti.

Claude chiamerà lo strumento chart con i tuoi parametri, riceverà un JSON strutturato e descriverà la carta a parole.

Transiti

Quali transiti significativi dei pianeti lenti si verificheranno nella mia carta natale nel corso del 2027?

Claude eseguirà due chiamate allo strumento: prima transits (istantanea corrente), poi transit-calendar (intervallo). Interpretare i trend.

Vedic Mahadasha

Avvia la Vimshottari Mahadasha per una persona nata il 22.07.1985 alle 06:45 a Mumbai. In quale periodo si trova attualmente?

Tramite lo strumento vedic/dashas/vimshottari/maha — timestamp UTC preciso del periodo corrente.

Synastry

Confronta due carte: A — 10.06.1988 09:15 Londra, B — 22.11.1991 22:40 Berlino. Quali sono gli aspetti incrociati più forti?

Strumento synastry con due blocchi chart + interpretazione del punteggio di compatibilità.

Tarocchi

Estrai 3 carte Rider-Waite-Smith: Passato — Presente — Futuro. Domanda: «dovrei accettare il nuovo lavoro?». Seed = 42.

tarot/rider-waite/spread con seed fisso per riproducibilità.

Elenco di tutti gli strumenti

Dopo aver collegato il server chiedi a Claude:

Elenca tutti gli strumenti AstroWay.

Oppure da riga di comando:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (avvia il server stdio; le chiamate protocollari a tool-list vengono effettuate dal client MCP)

Configurazione

Variabile	Default	Descrizione	Da versione
ASTROWAY_API_KEY	(obbligatoria)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Override per ambienti self-hosted/staging.	0.1.0
ASTROWAY_TOOL_GROUPS	(tutti i gruppi)	Elenco separato da virgole di prefissi per limitare il catalogo (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 salta i gruppi LLM-backed (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug — livello di logging su stderr.	0.8.0
LOG_FILE	(non scritto)	Percorso del file per duplicare i log.	0.8.0
MCP_FLAT_TOOLS	0	1 restituisce nomi flat pre-v0.9 (chart invece di astroway_western_chart). Legacy.	0.9.0

Perché MCP e non integrazione diretta

Un LLM generico (senza grounding) dirà «da qualche parte a luglio Saturno formerà un trigono con il tuo Giove» — senza data precisa, con un drift di ±15 giorni. Un agente MCP esegue tool_use POST /v1/transits e restituisce un timestamp UTC al secondo, usando il vero Swiss Ephemeris.

Il vantaggio non è nell’LLM, ma nella garanzia che la matematica sia reale — non inventata.

Distribuzione del pacchetto

• mcp.so listing: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: in attesa di approvazione (a maggio 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Link utili

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 Docs API: /docs/api/
• 🔑 Registrati: /dashboard/sign-up
• 💰 Prezzi: /pricing/
• 🌐 Repo pubblico (MIT): github.com/astroway/astroway-mcp