Agent setup

Connect the AstroWay API to AI agents over MCP (Model Context Protocol). The same 782-tool 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

782 tools in one answer is 2.9 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	104	389 KB
Vedic	/mcp/vedic	192	970 KB
Chinese metaphysics	/mcp/chinese	60	202 KB
Hellenistic and traditional	/mcp/hellenistic	59	240 KB
Tarot	/mcp/tarot	79	209 KB
Numerology	/mcp/numerology	64	158 KB
Human Design	/mcp/human-design	27	125 KB
Forecasting	/mcp/forecast	43	209 KB
Relationships	/mcp/relationships	42	247 KB
Psychological	/mcp/psychological	28	107 KB
Divination and esoterica	/mcp/divination	79	185 KB
Applied readings	/mcp/applied	45	148 KB
Reports	/mcp/reports	42	209 KB
Platform	/mcp/platform	42	119 KB

Measured on production 2026-09-21. /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 782.

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.

terminal

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

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

Claude Desktop Hosted MCP via config

Claude Code One CLI command

Cursor Hosted MCP via config

VS Code Copilot Chat, Agent mode

Windsurf Cascade MCP

Cline npx stdio package

Codex CLI npx stdio package

CI / raw HTTP

No client at all - the hosted endpoint speaks JSON-RPC over HTTP. List the tools with a Bearer token:

terminal

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

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.

terminal

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:

response, abridged

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

On the endpoints where we generate text, you can pay for the tokens yourself. Two headers, both or neither:

terminal

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

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