# MCP — connessione Claude / Cursor Il server Model Context Protocol di **AstroWay** espone **tutti gli {siteMeta.endpoints} 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](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 Inizia subito senza npm — scegli il tuo client. Prima di installare, prendi la tua chiave su [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 crediti/mese gratis). Clicca il pulsante — Cursor si aprirà, ti chiederà di confermare e aggiungerà automaticamente la configurazione: Installa in Cursor → :::caution[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](https://api.astroway.info/dashboard/keys). 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`). ::: 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. Per Cline / Continue / Windsurf o versioni vecchie di Claude Desktop / Cursor: ```json { "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 ```bash 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`: ```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_..." } } } } ``` L'uptime reale dell'endpoint hosted è visibile su [status.astroway.info](https://status.astroway.info). Incidenti superiori a 5 minuti vengono pubblicati come postmortem entro 5 giorni lavorativi (secondo [/sla/](/sla/)). ## Stdio (npm) — per lo sviluppo locale [`@astroway/mcp`](https://www.npmjs.com/package/@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](https://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/` 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](https://search.sigstore.dev/)) — 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`: ```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`: ```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: ```json { "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: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## 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/ (Node/)` - `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: ```jsonc { "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__` 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: ```bash 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](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** in attesa di approvazione (a maggio 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Link utili - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 Docs API: [/docs/api/](/docs/api/) - 🔑 Registrati: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Prezzi: [/pricing/](/pricing/) - 🌐 Repo pubblico (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)