Cosmic Ephemeris MCP server

R231 is live: MCP exposes all 78 calculation operations under the same route scopes and plan entitlements as REST.

A stateless, server-side agent adapter for the 78 live Cosmic Ephemeris calculations.

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

Security and billing boundary

  • Authenticate with an Cosmic Ephemeris API key or a five-minute OAuth client-credentials token. Never put either credential in tool arguments, prompts, browser JavaScript, mobile bundles, URLs, 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.
  • Retired minor-body operations are not advertised or callable. No prompt, resource, file, URL-fetch, arbitrary route, or customer credential is exposed as an MCP tool.

OAuth client credentials

Confidential machine clients can discover authorization metadata at /.well-known/oauth-authorization-server and MCP resource metadata at /.well-known/oauth-protected-resource. Request a token from /oauth/token with HTTP Basic authentication: the API-key UUID is the client ID, the raw API key is the client secret, grant_type is client_credentials, and resource must be exactly https://api.cosmicephemeris.com/mcp.

curl https://api.cosmicephemeris.com/oauth/token \
  --request POST \
  --user ":" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "resource=https://api.cosmicephemeris.com/mcp" \
  --data-urlencode "scope=astro:birth-chart"

The opaque token expires in 300 seconds, is bound to the MCP resource, inherits the key’s account, plan, environment, budget, and revocation state, and can only narrow live scopes. At most ten unexpired tokens exist per key. A bearer token replayed against a direct /api/astro/* request is rejected. This flow is for confidential machine clients; it is not browser sign-in, authorization-code/PKCE, dynamic registration, or user delegation.

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: cosmicephemeris_calculate. Legacy initialize/session transport is intentionally not enabled.

Discover the server

curl https://api.cosmicephemeris.com/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.cosmicephemeris.com/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: cosmicephemeris_calculate' \
  --data '{
    "jsonrpc":"2.0",
    "id":"chart-1",
    "method":"tools/call",
    "params":{
      "name":"cosmicephemeris_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.