MCP - connessione Claude / Cursor

Il server Model Context Protocol di AstroWay espone tutti i 771 endpoint come strumenti per l’agente AI. Due modalità - entrambe supportate nativamente da tutti i client compatibili con MCP.

Modalità	URL / comando	Quando scegliere
Hosted HTTP	https://mcp.astroway.info/mcp	Claude Web (claude.ai nel browser), Claude Desktop / Cursor / Code newcomers senza npm, o quando desideri zero-install
Stdio (npm)	npx @astroway/mcp	Utenti esperti di Cursor, sviluppo locale, attenti alla privacy (la chiave non lascia mai la tua macchina), offline-ready

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

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

Hosted (mcp.astroway.info) - zero install

Avvio rapido senza npm - scegli il tuo client. Prima dell’installazione, ottieni la chiave su api.astroway.info/dashboard/sign-up (10.000 crediti/mese gratuitamente).

Cursor (un clic)

Clicca il pulsante - Cursor si aprirà, ti chiederà conferma e aggiungerà automaticamente la voce:

Installa in Cursor →

Passaggio obbligatorio 2 - altrimenti non funzionerà

Cursor non è in grado di sostituire il segreto dal deeplink - in ~/.cursor/mcp.json verrà scritto il letterale Bearer YOUR_API_KEY, al quale il server risponderà 403 invalid_format.

Dopo aver cliccato il pulsante:

1. Impostazioni di Cursor (⚙️ angolo in alto a destra) → Tools & MCP → trova astroway-hosted nell’elenco.
2. Clicca i tre puntini (⋯) accanto al server → Modifica configurazione.
3. Nel campo Authorization sostituisci Bearer YOUR_API_KEY con Bearer aw_test_… (o aw_live_…) - la tua chiave reale dalla Dashboard.
4. Salva → riapri l’elenco MCP → assicurati che lo stato sia enabled + punto verde + contatore 780+ tools enabled.

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

Nota

Cursor impone un limite alla lunghezza dei nomi: server_name:tool_name ≤ 60 caratteri. Circa 90 degli oltre 780 strumenti (principalmente i gruppi hellenistic_*, psychological_*, zi_wei_*, zodiac_* e numerology_*) vengono filtrati da Cursor e non saranno disponibili tramite LLM. Gli altri ~690 funzionano. In Claude Desktop non esiste tale limite - il catalogo è completo.

Claude Desktop

Settings → Developer → Edit Config apre claude_desktop_config.json. Questo file esegue solo comandi locali: la voce con il solo url viene ignorata con il messaggio “Some MCP servers couldn’t be loaded”. Il server hosted si connette tramite il bridge mcp-remote, che richiede 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_..." }
    }
  }
}

Chiudi completamente Claude Desktop (Cmd+Q) e riaprilo. La chiave si trova in env, perché Claude Desktop su Windows interrompe l’argomento allo spazio dopo Bearer.

La finestra di dialogo Add custom connector in Settings → Connectors accetta solo nome e URL; non c’è un campo per l’header Authorization, quindi la chiave AstroWay non può essere passata tramite essa al momento.

Configurazione JSON (manuale)

Per Cursor, Cline, Continue e Windsurf, che accettano direttamente un url remoto:

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

Percorsi dei file di configurazione:

• Cursor: ~/.cursor/mcp.json (globale) o .cursor/mcp.json (nello spazio di lavoro)
• Cline (VS Code): .cline/mcp.json nello spazio di lavoro
• 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":"…"}

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, …

Limiti di frequenza

L’endpoint hosted è protetto da un limite a 3 livelli: strato Cloudflare DDoS + edge proxy 120 req/min/IP + in-memory bucket 60/60s/(IP+key). I client MCP reali (Claude Desktop, Cursor) non si avvicinano a questi limiti - non effettuano richieste a raffica. Se la tua automazione / CI richiede > 120 req/min - usa la modalità stdio (non ci sono limiti, va direttamente tramite api.astroway.info/v1/* con il tuo rate-limit tariffario).

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

Se l’endpoint hosted restituisce 5xx, il client MCP vedrà un errore durante tools/list. Questo non influisce sui client stdio - essi avviano un pacchetto npm locale che si connette direttamente a api.astroway.info/v1/* senza lo strato hosted intermedio.

Fallback per integrazioni critiche: aggiungi un secondo server MCP nella configurazione con la 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. Gli incidenti > 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 sottoprocesso. Un unico pacchetto npm, integrazione nativa con Claude Desktop, Cursor e qualsiasi client compatibile con MCP.

Come funziona

L’elenco degli strumenti viene generato al momento del build dalla specifica OpenAPI live (api.astroway.info/v1/openapi.json). Ogni rilascio del pacchetto include automaticamente tutti i nuovi endpoint - non è necessario mantenere nulla manualmente.

Ogni endpoint diventa uno strumento del tipo:

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

Ogni rilascio viene anche spedito con la provenienza SLSA (Sigstore-attested) - questa è una garanzia che il pacchetto npm è stato costruito esattamente dal commit nel repository pubblico.

Installazione

Claude Desktop (macOS)

Aggiungi a ~/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 indicatore 🛠️ con il numero di strumenti caricati.

Cursor

Aggiungi a ~/.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 compatibile con MCP. 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 radice dello spazio di lavoro
Continue	~/.continue/config.json (blocco mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	flag di anteprima → mcp.json nello spazio di lavoro
Estensione VS Code MCP	~/.vscode/mcp.json

Altri client MCP

Avvia come server stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Consiglio

Ottieni la chiave su api.astroway.info/dashboard/sign-up. Livello gratuito - 10 000 crediti/mese, senza carta.

Privacy - da v1.0.0+

Questo server MCP non invia nulla ad AstroWay eccetto le chiamate API che gli chiedi di eseguire. Nessuna telemetria, nessun analytics, nessun interruttore opt-in/opt-out - silenzio per impostazione predefinita.

Le richieste in uscita contengono due header identificativi affinché il backend AstroWay possa distinguere il traffico MCP dal traffico HTTP diretto nei propri log:

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

Nessuno di essi contiene ID di sessione, fingerprint della macchina o qualsiasi cosa personale. Questa è la semantica standard di User-Agent - ogni strumento CLI invia informazioni simili.

Registrazione di sottogruppi - da v1.0.0+

Se utilizzi solo una parte del catalogo - registra un sottogruppo affinché la finestra di contesto dell’LLM rimanga compatta:

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

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

ASTROWAY_READONLY=1 salta tre gruppi che internamente richiamano LLM (ai, horoscope, reports) - utile quando desideri una matematica delle carte pura e deterministica senza spendere crediti per la generazione di testo.

Impegno di stabilità - da v1.0.0+

• Il catalogo è congelato per la durata della sessione. Oltre 780 strumenti, 12 prompt, 14 risorse sono incorporati nel pacchetto npm pubblicato al momento del build - nulla cambia durante la connessione. Se il tuo client memorizza nella cache tools/list dopo la prima chiamata - rimane corretto per l’intera sessione.
• Gli identificatori degli strumenti sono stabili all’interno di una versione major. Il nome sotto astroway_<group>_<tool> non verrà rinominato o eliminato all’interno di v1.x senza una nota di deprecazione in CHANGELOG.md e una disponibilità parallela di una versione minor.
• La forma di input dello strumento è stabile all’interno di una versione minor. Le restrizioni (regex, range, enum) arrivano nelle patch; l’aggiunta di un campo obbligatorio richiede un minor bump.
• Aggiornamento del catalogo: tramite reinstallazione. npm i -g @astroway/mcp@latest (o la forma npx -y @astroway/mcp nella tua configurazione) recupera il set corrente al successivo avvio.

Esempi di prompt

Dopo la connessione del server, chiedi all’AI:

Tema natale

Calcola il mio tema natale - nato il 15 marzo 1990, 14:30, Kiev. Descrivi il Sole, la Luna, l’Ascendente e trova gli aspetti stretti.

Claude richiamerà lo strumento chart con i tuoi parametri, riceverà un JSON strutturato e descriverà il tema a parole.

Transiti

Quali transiti significativi dei pianeti lenti influenzeranno il mio tema natale durante il 2027?

Claude effettua due chiamate allo strumento: prima transits (istantanea corrente), poi transit-calendar (intervallo). Interpreta le tendenze.

Mahadasha Vedica

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

Tramite lo strumento vedic/dashas/vimshottari/maha - il timestamp UTC esatto del periodo corrente.

Sinastria

Confronta due temi: 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 un seed fisso per la riproducibilità.

Elenco di tutti gli strumenti

Dopo la connessione, chiedi a Claude:

Elenca tutti gli strumenti astroway.

Oppure dalla riga di comando:

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)

Configurazione

Variabile	Predefinito	Descrizione	Dalla versione
ASTROWAY_API_KEY	(obbligatorio)	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)	Prefissi separati da virgola per limitare il catalogo (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 salta i gruppi supportati da LLM (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 la duplicazione dei 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, non integrazione diretta

Un LLM generico (senza grounding) dirà “a luglio Saturno formerà un trigono al tuo Giove” - senza una data precisa, con una deriva di ±15 giorni. L’agente MCP effettua tool_use POST /v1/transits e restituisce un timestamp UTC al secondo, basato sul 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

Riferimenti

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