Configurazione dell'agente
Collega l’API AstroWay agli agenti AI tramite MCP (Model Context Protocol). Il catalogo è disponibile in due modi, entrambi con le tue chiavi aw_test_* / aw_live_*:
- Hosted (HTTP):
https://mcp.astroway.info/mcp, nessuna installazione, autenticazione tramite token Bearer. - Stdio (npx):
npx @astroway/mcp, sottoprocesso locale, autenticazione tramite variabile d’ambiente, funziona offline.
Ottieni una chiave gratuita nella dashboard, poi scegli il tuo client.
Un solo dominio invece dell’intero catalogo
Sezione intitolata “Un solo dominio invece dell’intero catalogo”783 strumenti in un’unica risposta sono 2.9 MB che l’agente deve leggere prima di sceglierne uno. La maggior parte dei client si arrende molto prima.
https://mcp.astroway.info/mcp/<dominio> restituisce un solo ambito invece di tutto. La configurazione è la stessa, cambia solo l’URL.
| Dominio | URL | Strumenti | Dimensione di tools/list |
|---|---|---|---|
| Nucleo dell’astrologia | /mcp/core | 104 | 389 KB |
| Vedica | /mcp/vedic | 192 | 970 KB |
| Metafisica cinese | /mcp/chinese | 60 | 202 KB |
| Ellenistica e tradizione | /mcp/hellenistic | 59 | 240 KB |
| Tarocchi | /mcp/tarot | 79 | 209 KB |
| Numerologia | /mcp/numerology | 64 | 158 KB |
| Human Design | /mcp/human-design | 27 | 125 KB |
| Previsioni | /mcp/forecast | 43 | 209 KB |
| Relazioni | /mcp/relationships | 42 | 247 KB |
| Psicologica | /mcp/psychological | 28 | 107 KB |
| Divinazione ed esoterismo | /mcp/divination | 79 | 185 KB |
| Letture applicate | /mcp/applied | 45 | 148 KB |
| Report | /mcp/reports | 42 | 209 KB |
| Piattaforma | /mcp/platform | 42 | 119 KB |
Misurato in produzione il 2026-09-21. /mcp continua a restituire l’intero catalogo, quindi nulla di ciò che era già configurato si è rotto. Il controllo del saldo e la stima del costo di una chiamata sono presenti in ogni dominio, perché anche un agente limitato all’astrologia vedica deve sapere quanto costa una chiamata.
GET /domains restituisce questo stesso elenco in JSON, senza chiave. Un dominio sconosciuto è un 404 con l’elenco di quelli reali, non una restituzione silenziosa di tutti i 783.
Documentazione senza chiave: /mcp/docs
Sezione intitolata “Documentazione senza chiave: /mcp/docs”La prima domanda di un agente non è mai “calcola la carta”. Suona come “cosa sa fare questa API, com’è fatta una chiamata e quanto mi costerà”. Si può rispondere a tutte e tre senza chiave: https://mcp.astroway.info/mcp/docs non consuma alcun credito, quindi non chiede nemmeno l’autenticazione.
| Strumento | Cosa fa |
|---|---|
find_endpoint | Cerca tra tutte le 770 operazioni. Per ciascuna restituisce metodo, URL, prezzo in crediti, piano, campi obbligatori del body e link alla documentazione |
search_docs | Cerca tra le 281 pagine delle guide, in ucraino e in inglese, con l’elenco delle sezioni di ciascuna |
read_doc | Restituisce una singola pagina in markdown |
list_docs | L’intero indice, raggruppato per sezioni |
Hanno un prezzo 700 operazioni su 770, altre 37 sono contrassegnate come operazioni che rispondono senza chiave. In altre parole, il costo di uno scenario si può calcolare prima ancora di avere un account.
curl https://mcp.astroway.info/mcp/docs \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_endpoint","arguments":{"query":"solar return","limit":2}}}'read_doc legge solo le pagine presenti nell’indice. Qualsiasi altro percorso riceve un rifiuto, e nessuna richiesta esce verso l’esterno.
Chiedi meno dell’intera risposta
Sezione intitolata “Chiedi meno dell’intera risposta”Ogni strumento accetta due parametri oltre ai propri: fields (un elenco di percorsi separati da virgola, relativi a data) e precision (quante cifre decimali mantenere). Vanno alla stessa API che si usa via REST, e la differenza in token non è retorica.
| Chiamata della carta natale tramite MCP | Byte |
|---|---|
| senza parametri, come prima del 21.09.2026 | 91 737 |
| senza parametri, oggi | 72 484 |
precision: 2 | 61 356 |
fields: "planets.name,planets.longitude,houses.cusp" più precision: 2 | 1 182 |
Misurato in produzione il 2026-09-21. I crediti sono gli stessi in tutte e quattro le righe: la differenza la paga chi legge la risposta.
Un percorso che non corrisponde a nessun campo torna indietro in _fields_unmatched. Un elenco in cui non corrisponde nulla è un 400 FIELDS_UNKNOWN con l’elenco, non una risposta vuota. Descrizione completa di entrambi i parametri: convenzioni dell’API.
Scegli il tuo client
Sezione intitolata “Scegli il tuo client”CI / HTTP diretto
Sezione intitolata “CI / HTTP diretto”Del tutto senza client: l’endpoint hosted parla JSON-RPC su HTTP. Elenco degli strumenti con token Bearer:
curl https://mcp.astroway.info/mcp \-H "Authorization: Bearer aw_live_YOUR_KEY" \-H "Content-Type: application/json" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Function calling senza MCP
Sezione intitolata “Function calling senza MCP”Se il tuo agente parla il linguaggio del function calling di OpenAI o Anthropic anziché MCP, chiedi all’API le definizioni degli strumenti già pronte e passale direttamente al modello. Sono generate dal documento OpenAPI, quindi lo schema che il modello compila è lo stesso schema che l’endpoint valida.
curl "https://api.astroway.info/v1/agent/tools?format=openai" \-H "X-Api-Key: aw_live_YOUR_KEY"La risposta ha due metà. tools corrisponde esattamente al contratto del vendor e non contiene nulla di nostro, quindi puoi inserirlo nella chiamata al modello così com’è: una chiave in più dentro l’oggetto di uno strumento è un 400 dalla loro parte. executors dice come eseguire ogni strumento e ha le stesse chiavi che restituirà il modello:
{"tools": [ { "type": "function", "function": { "name": "astroway_post_chart", "description": "Natal chart...", "parameters": { "type": "object", "required": ["date", "time", "latitude", "longitude"], "properties": { "...": {} } } } }],"executors": { "astroway_post_chart": { "method": "POST", "path": "/v1/chart", "credits": 20, "group": "Core" }},"count": 26, "totalMatched": 26, "totalAvailable": 751, "truncated": false}A quel punto il tuo esecutore sono cinque righe: trovare il nome in executors, inviare gli argomenti del modello come body JSON a quel percorso con la tua X-Api-Key, restituire la risposta al modello. Nessuno strumento contiene credenziali, quindi questo elenco si può mettere in cache senza rischi.
Sei tu a scegliere cosa vede il modello. Di default è un set iniziale curato di 26 strumenti, non l’intero catalogo: OpenAI limita una richiesta a 128 funzioni, e i modelli iniziano a scegliere peggio molto prima di quel limite. Restringi o allarga con select=all, select=group:Vedic, select=paths:/chart,/synastry, filtra all’interno con q=, limita con limit= (massimo 128). Nulla sparisce in silenzio: totalMatched e notes dicono cosa è rimasto fuori. Aggiungi format=anthropic per ottenere { name, description, input_schema }.
La chiamata è gratuita e non consuma crediti.
La tua chiave per il modello
Sezione intitolata “La tua chiave per il modello”Sugli endpoint in cui generiamo testo puoi pagare tu i token. Due header, entrambi o nessuno:
curl https://api.astroway.info/v1/ai/explain-aspect \-H "X-Api-Key: aw_live_YOUR_KEY" \-H "X-Provider: anthropic" \-H "X-Provider-Key: sk-ant-YOUR_PROVIDER_KEY" \-H "Content-Type: application/json" \-d '{"planet1":"Saturn","planet2":"Moon","aspectType":"Square"}'X-Provider è uno tra openai, anthropic, google, groq, mistral, openrouter, deepseek, together; l’indirizzo di ciascuno è fissato dalla nostra parte e non viene mai preso dalla richiesta. X-Provider-Model è facoltativo e sostituisce il modello di default.
Non c’è ripiego sulla nostra catena. Se la tua chiave non funziona, ricevi lo stato e il messaggio del provider, non una risposta pagata da noi: un ripiego silenzioso consumerebbe i nostri token per una richiesta che consideravi tua, e sarebbe impossibile accorgersene.
Una chiamata del genere costa 5 crediti invece del prezzo dell’endpoint. Calcoliamo comunque la carta, costruiamo il prompt ed eseguiamo le protezioni; il completamento l’hai comprato tu.
La tua chiave non viene registrata nei log, salvata né messa in cache. Viaggia in un header, perché il body della richiesta viene hashato in due chiavi di cache, e il nostro log delle richieste non scrive affatto gli header. Un errore del provider che ha citato la tua chiave viene oscurato prima di finire nei nostri log o nella tua risposta. Una chiamata con la tua chiave aggira entrambe le cache in entrambe le direzioni: non riceverà mai una risposta prodotta da noi, e la sua risposta non arriverà mai a qualcun altro.
Gli header sono nella specifica. Ogni percorso che li accetta dichiara X-Provider, X-Provider-Key e X-Provider-Model in /v1/openapi.json, quindi un client generato li collegherà come qualsiasi altro parametro, e questa pagina non gli serve. Sono dichiarati solo dove chiamiamo davvero un modello: puoi inviarli a /chart, ma non succederà nulla e pagherai il prezzo normale dell’endpoint.
Specifiche leggibili dalle macchine
Sezione intitolata “Specifiche leggibili dalle macchine”Vuoi collegare direttamente la REST API o dare la specifica in pasto al tuo agente?
- AGENTS.md:
/AGENTS.md, istruzioni per l’agente (cosa si può chiamare senza chiave, contratto della richiesta, envelope della risposta, header dei limiti) - OpenAPI:
/v1/openapi.json - llms.txt:
/llms.txt· testo completo/llms-full.txt - Postman:
/postman/astroway-api.json - SDK: TypeScript, Python, PHP