AstroAPI MCP server

A stateless, server-side agent adapter for the 35 live AstroAPI calculations.

The endpoint is https://api.astroapi.io/mcp. It implements the MCP 2026-07-28 Streamable HTTP request/response contract and exposes one tool: astroapi_calculate. The tool accepts a documented operation name and that operation's exact JSON input.

Security and billing boundary

• Send an AstroAPI key in the HTTP Authorization: Bearer header or X-API-Key header. Never put it in tool arguments, prompts, browser JavaScript, mobile bundles, or model-visible text.
• The endpoint rejects every request carrying an Origin header. It is for trusted agent hosts and backends, not direct browser calls or a hosted browser widget.
• Each tool call is routed through the ordinary calculation endpoint. Existing API-key scope, expiry, revocation, account quota, concurrency, project, environment, workspace-owner billing, and per-key budget rules apply unchanged.
• An admitted calculation uses its normal quota unit even if its input is invalid or calculation fails. Do not automatically retry.
• The three unavailable JPL minor-body contracts are not advertised. No prompt, resource, file, URL-fetch, arbitrary route, or customer credential is exposed as an MCP tool.

Protocol boundary

This first release serves only the current stateless protocol revision 2026-07-28. Every POST must use Content-Type: application/json, matching MCP-Protocol-Version and Mcp-Method headers, and the same protocol version in params._meta. tools/call also requires Mcp-Name: astroapi_calculate. Legacy initialize/session transport is intentionally not enabled.

Discover the server

curl https://api.astroapi.io/mcp \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc":"2.0",
    "id":"discover-1",
    "method":"server/discover",
    "params":{"_meta":{
      "io.modelcontextprotocol/protocolVersion":"2026-07-28",
      "io.modelcontextprotocol/clientCapabilities":{},
      "io.modelcontextprotocol/clientInfo":{"name":"your-agent-host","version":"1.0.0"}
    }}
  }'

server/discover and tools/list return stable public metadata and may be cached for one hour. The discovery response advertises only 2026-07-28 and the tools capability.

Call one calculation

curl https://api.astroapi.io/mcp \
  --request POST \
  --header 'Authorization: Bearer YOUR_SERVER_SIDE_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: tools/call' \
  --header 'Mcp-Name: astroapi_calculate' \
  --data '{
    "jsonrpc":"2.0",
    "id":"chart-1",
    "method":"tools/call",
    "params":{
      "name":"astroapi_calculate",
      "arguments":{
        "operation":"birth-chart",
        "input":{"date":"2000-01-01","time":"12:00","timezone":"UTC","lat":0,"lon":0}
      },
      "_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientCapabilities":{},
        "io.modelcontextprotocol/clientInfo":{"name":"your-agent-host","version":"1.0.0"}
      }
    }
  }'

A completed call returns MCP text content plus structuredContent.status and structuredContent.response. Calculation/authentication denials are completed tool results with isError: true; JSON-RPC errors are reserved for malformed MCP requests and unsupported methods.

Choosing operations and scopes

tools/list contains the exact sorted operation enum. Give an agent a narrowly scoped key such as astro:birth-chart instead of astro:* whenever possible. Shared workspace keys remain billed to the immutable workspace owner. Use a small per-key monthly budget to bound agent activity.

Use the API reference for each operation's strict input schema, authentication guide for key controls, and protected API Keys dashboard for scopes, projects, environments, budgets, and revocation.