Agent setup
Connect the AstroWay API to AI agents over MCP (Model Context Protocol). The catalog is available two ways, both authenticated with your existing aw_test_* / aw_live_* keys:
- Hosted (HTTP):
https://mcp.astroway.info/mcp, zero install, Bearer-token auth. - Stdio (npx):
npx @astroway/mcp, local subprocess, env-var auth, offline-ready.
Get a free key in the dashboard, then pick your client.
One subject instead of the whole catalogue
Section titled “One subject instead of the whole catalogue”843 tools in one answer is 3.4 MB an agent has to read before it can pick anything. Most clients give up long before that.
https://mcp.astroway.info/mcp/<domain> serves one subject instead. Same config, only the URL changes.
| Domain | URL | Tools | tools/list size |
|---|---|---|---|
| Core astrology | /mcp/core | 108 | 458 KB |
| Vedic astrology | /mcp/vedic | 236 | 1.2 MB |
| Chinese metaphysics | /mcp/chinese | 62 | 212 KB |
| Hellenistic and traditional | /mcp/hellenistic | 83 | 336 KB |
| Tarot | /mcp/tarot | 86 | 244 KB |
| Numerology | /mcp/numerology | 88 | 253 KB |
| Human Design | /mcp/human-design | 27 | 122 KB |
| Forecasting | /mcp/forecast | 45 | 207 KB |
| Relationships | /mcp/relationships | 45 | 249 KB |
| Psychological astrology | /mcp/psychological | 45 | 165 KB |
| Divination and esoterica | /mcp/divination | 79 | 195 KB |
| Applied readings | /mcp/applied | 47 | 163 KB |
| Reports | /mcp/reports | 43 | 227 KB |
| Platform | /mcp/platform | 45 | 132 KB |
Measured on production 2026-11-07.
/mcp still serves the whole catalogue, so nothing configured earlier broke. Balance checks and cost estimates are on every domain, because an agent scoped to Vedic still needs to know what a call will cost.
GET /domains returns the same list as JSON, with no key. An unknown domain is a 404 naming the real ones, never a quiet fall back to all 843.
Documentation without a key: /mcp/docs
Section titled “Documentation without a key: /mcp/docs”An agent’s first question is never “calculate a chart”. It is “what can this API do, what does the call look like, and what will it cost me”. All three can be answered without a key: https://mcp.astroway.info/mcp/docs spends no credits, so it asks for no authorisation.
| Tool | What it does |
|---|---|
find_endpoint | Searches all 770 operations. For each one: method, URL, credit cost, tier, required body fields and a link to its reference page |
search_docs | Searches 281 guide pages, Ukrainian and English, with each page’s section list |
read_doc | Returns one page as markdown |
list_docs | The whole index, grouped by section |
700 of the 770 operations carry a price and 37 more are marked as answering without a key, so a workflow can be costed before an account exists.
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 reads only pages that are in the index. Any other path is refused, and no request leaves the server.
Ask for less than the whole response
Section titled “Ask for less than the whole response”Every tool takes two parameters on top of its own: fields (comma-separated dotted paths, relative to data) and precision (decimal places to keep). They reach the same API they reach over REST, and the difference in tokens is not rhetorical.
| Natal chart call over MCP | Bytes |
|---|---|
| no parameters, as it stood before 2026-09-21 | 91,737 |
| no parameters, today | 72,484 |
precision: 2 | 61,356 |
fields: "planets.name,planets.longitude,houses.cusp" plus precision: 2 | 1,182 |
Measured on production 2026-09-21. Credits are the same on all four rows: the difference is paid by whoever reads the answer.
A path that matched nothing comes back in _fields_unmatched. A list where nothing matched is a 400 FIELDS_UNKNOWN naming the paths, not an empty answer. Both parameters in full: API conventions.
Choose your client
Section titled “Choose your client”Chat apps: claude.ai
Section titled “Chat apps: claude.ai”No key needed: the app signs in to your AstroWay account itself.
- In claude.ai open Settings → Connectors → Add custom connector.
- Paste the URL
https://mcp.astroway.info/mcp, pick Sign in when needed under Authentication and click Add. - In a chat turn the connector on (”+” → Connectors) and ask for, say, a natal chart.
- On the first call the app opens the AstroWay sign-in and an approval page. After “Allow” the call runs.
The server lists its tools without sign-in, so claude.ai suggests “No sign-in”. With that choice the connector is added, but every call gets a 401 and no sign-in window.
Calls are charged to your account’s credits, the same as with a key. Connected apps are listed on the keys page of the dashboard, and you disconnect them there.
CI / raw HTTP
Section titled “CI / raw HTTP”No client at all - the hosted endpoint speaks JSON-RPC over HTTP. List the tools with a Bearer token:
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 without MCP
Section titled “Function calling without MCP”If your agent speaks OpenAI or Anthropic function calling rather than MCP, ask the API for the tool definitions and hand them straight to the model. They are generated from the OpenAPI document, so the schema the model fills is the schema the endpoint validates.
curl "https://api.astroway.info/v1/agent/tools?format=openai" \-H "X-Api-Key: aw_live_YOUR_KEY"The response has two halves. tools is vendor-exact and carries nothing of ours, so you can spread it into a chat completion as it is; an unexpected key inside a tool object is a 400 at their end. executors tells you how to run each tool, keyed by the same name the model will call back with:
{"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}Your executor is then five lines: look the name up in executors, send the model’s arguments as the JSON body to that path with your X-Api-Key, return the response to the model. No tool carries a credential, which is why this list is safe to cache.
Choose what the model sees. The default is a curated starter set of 26, not the whole catalogue: OpenAI caps a request at 128 functions and models get worse at choosing long before that. Narrow or widen with select=all, select=group:Vedic, select=paths:/chart,/synastry, filter inside that with q=, and cap with limit= (max 128). Nothing is dropped quietly: totalMatched and notes say what was left out. Add format=anthropic for { name, description, input_schema } instead.
The call is free and does not spend credits.
Bring your own model key
Section titled “Bring your own model key”On the endpoints where we generate text, you can pay for the tokens yourself. Two headers, both or neither:
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 is one of openai, anthropic, google, groq, mistral, openrouter, deepseek, together; the endpoint for each is fixed on our side and never taken from the request. X-Provider-Model is optional and overrides the default model for that provider.
There is no fallback to our own chain. If your key fails, you get the provider’s status and message back rather than an answer we paid for: a silent fallback would spend our tokens on a request you believed you were funding, and you would have no way to notice.
Such a turn costs 5 credits instead of the endpoint price. We still compute the chart, build the prompt and run the safety guardrails; you bought the completion.
Your key is never logged, stored or cached. It travels in a header because the request body is hashed into two cache keys, and our request log records no headers at all. A provider error that quotes your key back is redacted before it reaches our logs or your response. A BYOK turn bypasses both caches in each direction: it is never answered from a completion we produced, and its answer never becomes one somebody else is served.
The headers are in the spec. Every path that accepts them declares X-Provider, X-Provider-Key and X-Provider-Model in /v1/openapi.json, so a generated client wires them like any other parameter instead of needing this page. They are declared only where we actually call a model: sending them to /chart is accepted and does nothing, and you pay the endpoint price as usual.
Machine-readable specs
Section titled “Machine-readable specs”Prefer wiring the REST API directly, or feeding a spec to your own agent?
- AGENTS.md:
/AGENTS.md, agent instructions (what you can call with no key, the request contract, the response envelope, rate-limit headers) - OpenAPI:
/v1/openapi.json - llms.txt:
/llms.txt· full text/llms-full.txt - Postman:
/postman/astroway-api.json - SDKs: TypeScript, Python, PHP, Go, C#
Hosted or npx? Hosted needs nothing installed and is the only one that takes fields and precision. The npx package keeps the key in a local environment variable and suits clients that only start local commands.
Which URL do I give my client? The domain for your subject, from the table above. /mcp has all 843 tools, which most clients read slowly or cut off.
How do I know what a call costs? Every tool description ends with a [Cost: ...] line. astroway_cost_estimate prices several calls without running them, and find_endpoint on /mcp/docs answers the same question with no key at all.
Can I try it without spending credits? Yes, with an aw_test_* sandbox key from the dashboard.
Why does Claude Desktop need mcp-remote? Its config file only starts local commands and skips an entry with a bare url. The Claude Desktop page has the block.
Is AstroWay in the MCP Registry? Yes: every server above is listed in the official registry as info.astroway/*, so registry-aware clients can find it by name.