Configuração do agente
Liga a API AstroWay a agentes de IA através de MCP (Model Context Protocol). O catálogo está disponível de duas formas, ambas com as tuas chaves aw_test_* / aw_live_*:
- Hosted (HTTP):
https://mcp.astroway.info/mcp, sem instalação, autenticação por token Bearer. - Stdio (npx):
npx @astroway/mcp, subprocesso local, autenticação por variável de ambiente, funciona offline.
Obtém uma chave gratuita no dashboard e depois escolhe o teu cliente.
Um domínio em vez do catálogo inteiro
Seção intitulada “Um domínio em vez do catálogo inteiro”843 ferramentas numa só resposta são 3.4 MB que o agente tem de ler antes de escolher uma. A maioria dos clientes desiste muito antes disso.
https://mcp.astroway.info/mcp/<domínio> devolve um só tema em vez de tudo. A configuração é a mesma, só muda o URL.
| Domínio | URL | Ferramentas | Tamanho de tools/list |
|---|---|---|---|
| Núcleo da astrologia | /mcp/core | 104 | 389 KB |
| Védica | /mcp/vedic | 192 | 970 KB |
| Metafísica chinesa | /mcp/chinese | 60 | 202 KB |
| Helenística e tradicional | /mcp/hellenistic | 59 | 240 KB |
| Tarot | /mcp/tarot | 79 | 209 KB |
| Numerologia | /mcp/numerology | 64 | 158 KB |
| Human Design | /mcp/human-design | 27 | 125 KB |
| Previsões | /mcp/forecast | 43 | 209 KB |
| Relações | /mcp/relationships | 42 | 247 KB |
| Psicológica | /mcp/psychological | 28 | 107 KB |
| Adivinhação e esoterismo | /mcp/divination | 79 | 185 KB |
| Leituras aplicadas | /mcp/applied | 45 | 148 KB |
| Relatórios | /mcp/reports | 42 | 209 KB |
| Plataforma | /mcp/platform | 42 | 119 KB |
Medido em produção a 2026-09-21. /mcp continua a devolver o catálogo inteiro, por isso nada do que já estava configurado deixou de funcionar. A verificação do saldo e a estimativa do custo de uma chamada existem em todos os domínios, porque um agente limitado à astrologia védica continua a precisar de saber quanto custa uma chamada.
GET /domains devolve esta mesma lista em JSON, sem chave. Um domínio desconhecido dá 404 com a lista dos verdadeiros, e não um regresso silencioso de todas as 843.
Documentação sem chave: /mcp/docs
Seção intitulada “Documentação sem chave: /mcp/docs”A primeira pergunta de um agente nunca é “calcula o mapa”. É “o que sabe fazer esta API, como é uma chamada e quanto me vai custar”. Pode responder às três sem chave: https://mcp.astroway.info/mcp/docs não gasta nenhum crédito, por isso também não pede autenticação.
| Ferramenta | O que faz |
|---|---|
find_endpoint | Pesquisa entre todas as 770 operações. Para cada uma devolve o método, o URL, o preço em créditos, o plano, os campos obrigatórios do corpo e a ligação para a referência |
search_docs | Pesquisa em 281 páginas de guias, em ucraniano e inglês, com a lista de secções de cada uma |
read_doc | Devolve uma página em markdown |
list_docs | O índice completo, agrupado por secções |
700 das 770 operações têm preço, e mais 37 estão marcadas como respondendo sem chave. Ou seja, o custo de um cenário pode ser calculado antes de existir uma conta.
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 lê apenas as páginas que estão no índice. Qualquer outro caminho é recusado, e nenhum pedido sai para fora.
Pede menos do que a resposta inteira
Seção intitulada “Pede menos do que a resposta inteira”Cada ferramenta aceita dois parâmetros além dos seus: fields (lista de caminhos separados por vírgulas, relativos a data) e precision (quantas casas decimais manter). Seguem para a mesma API que via REST, e a diferença em tokens não é retórica.
| Chamada de mapa natal via MCP | Bytes |
|---|---|
| sem parâmetros, como era até 21.09.2026 | 91 737 |
| sem parâmetros, hoje | 72 484 |
precision: 2 | 61 356 |
fields: "planets.name,planets.longitude,houses.cusp" mais precision: 2 | 1 182 |
Medido em produção a 2026-09-21. Os créditos são iguais nas quatro linhas: quem paga a diferença é quem lê a resposta.
Um caminho que não corresponde a nenhum campo volta em _fields_unmatched. Uma lista em que nada corresponde dá 400 FIELDS_UNKNOWN com a enumeração, e não uma resposta vazia. Descrição completa de ambos os parâmetros: convenções da API.
Escolhe o teu cliente
Seção intitulada “Escolhe o teu cliente”CI / raw HTTP
Seção intitulada “CI / raw HTTP”Sem cliente nenhum - o endpoint hosted fala JSON-RPC sobre HTTP. Lista de ferramentas com 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 sem MCP
Seção intitulada “Function calling sem MCP”Se o teu agente fala a linguagem de function calling da OpenAI ou da Anthropic, e não MCP, pede à API as definições de ferramentas já prontas e passa-as diretamente ao modelo. São geradas a partir do documento OpenAPI, por isso o esquema que o modelo preenche é o mesmo esquema que o endpoint valida.
curl "https://api.astroway.info/v1/agent/tools?format=openai" \-H "X-Api-Key: aw_live_YOUR_KEY"A resposta tem duas metades. tools corresponde exatamente ao contrato do fornecedor e não leva nada nosso, por isso pode ir tal como está na chamada ao modelo: uma chave a mais dentro do objeto de uma ferramenta dá 400 do lado deles. executors diz como executar cada ferramenta e tem as mesmas chaves que o modelo vai devolver:
{"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}O teu executor passa então a ter cinco linhas: encontrar o nome em executors, enviar os argumentos do modelo como corpo JSON para esse caminho com o teu X-Api-Key, devolver a resposta ao modelo. Nenhuma ferramenta contém credenciais, por isso esta lista pode ser guardada em cache sem risco.
Tu escolhes o que o modelo vê. Por omissão é um conjunto inicial curado de 26 ferramentas, e não o catálogo inteiro: a OpenAI limita um pedido a 128 funções, e os modelos começam a escolher pior muito antes desse limite. Restringe ou alarga com select=all, select=group:Vedic, select=paths:/chart,/synastry, filtra por dentro com q=, limita com limit= (máximo 128). Nada desaparece em silêncio: totalMatched e notes dizem o que ficou de fora. Acrescenta format=anthropic para obter { name, description, input_schema }.
A chamada é gratuita e não gasta créditos.
A tua própria chave do modelo
Seção intitulada “A tua própria chave do modelo”Nos endpoints onde geramos texto, podes pagar tu os tokens. Dois cabeçalhos, ou ambos, ou nenhum:
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 é um de openai, anthropic, google, groq, mistral, openrouter, deepseek, together; o endereço de cada um está fixado do nosso lado e nunca é tirado do pedido. X-Provider-Model é opcional e substitui o modelo por omissão.
Não há recurso à nossa cadeia. Se a tua chave falhar, recebes o estado e a mensagem do fornecedor, e não uma resposta paga por nós: um recurso silencioso gastaria os nossos tokens num pedido que consideravas teu, e seria impossível dar por isso.
Uma chamada destas custa 5 créditos em vez do preço do endpoint. Continuamos a calcular o mapa, montar o prompt e aplicar as salvaguardas; a geração foste tu que a compraste.
A tua chave não é registada, guardada nem posta em cache em lado nenhum. Vai num cabeçalho, porque o corpo do pedido é convertido em hash para duas chaves de cache, e o nosso registo de pedidos não escreve cabeçalhos de todo. Um erro do fornecedor que cite a tua chave é editado antes de chegar aos nossos logs ou à tua resposta. Uma chamada com a tua chave contorna ambas as caches nos dois sentidos: nunca recebe uma resposta feita por nós, e a resposta dela nunca chega a outra pessoa.
Os cabeçalhos estão na especificação. Cada caminho que os aceita declara X-Provider, X-Provider-Key e X-Provider-Model em /v1/openapi.json, por isso um cliente gerado liga-os como qualquer outro parâmetro e não precisa desta página. Só estão declarados onde de facto chamamos um modelo: podes enviá-los para /chart, mas nada acontece e pagas o preço normal do endpoint.
Especificações legíveis por máquina
Seção intitulada “Especificações legíveis por máquina”Queres ligar a API REST diretamente ou dar a especificação ao teu próprio agente?
- AGENTS.md:
/AGENTS.md, instruções para o agente (o que se pode chamar sem chave, contrato do pedido, envelope da resposta, cabeçalhos de limites) - OpenAPI:
/v1/openapi.json - llms.txt:
/llms.txt· texto completo/llms-full.txt - Postman:
/postman/astroway-api.json - SDK: TypeScript, Python, PHP