Cosmic Ephemeris MCP server

MCP exposes all 78 live calculation operations under the same route scopes, plan entitlements, quotas, and key controls as REST.

Two stateless, server-side tools for 78 live calculations plus Tarot, symbolic readings and supplemental Vedic systems.

The endpoint is https://api.cosmicephemeris.com/mcp. It implements the MCP 2026-07-28 Streamable HTTP request/response contract and exposes two tools: cosmicephemeris_calculate for the original 78 calculations and cosmicephemeris_symbolic for tarot, symbolic-reading, and vedic-systems. Each accepts a documented operation and its exact JSON input.

Planetary data and calculation evidence

Cosmic Ephemeris calculates planetary positions using JPL DE440 and DE441 data through Skyfield. Selected calculations are checked against recorded Swiss Ephemeris/Moshier reference results. MCP calls use the same calculation engine and conventions as REST and the SDKs. The published comparison evidence identifies the tested samples and settings.

Official MCP Registry

Cosmic Ephemeris is listed in the official MCP Registry as com.cosmicephemeris/mcp. Registry metadata version 1.1.0, published October 16, 2026, describes the 78 calculations plus Tarot, symbolic readings and Vedic calendars. The Registry lookup identifies https://api.cosmicephemeris.com/mcp and declares the required secret X-API-Key header. Registry availability is independent of our endpoint; a listing is not certification of every agent host. The runtime server version is also 1.1.0, but is versioned separately from Registry metadata and the protocol revision.

The Registry stores discovery metadata. It does not proxy calculations, issue credentials, or replace the scopes, quotas, budgets, billing, and revocation controls described below. Supported OAuth client credentials remain available directly from Cosmic Ephemeris. The Registry is in preview, so client discovery support may vary.

Security and billing boundary

  • Authenticate with a 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.

Load COSMIC_CLIENT_ID (the API-key UUID) and COSMIC_CLIENT_SECRET (the raw API key) from your trusted server-side secret manager before running this example.

curl https://api.cosmicephemeris.com/oauth/token \
  --request POST \
  --user "${COSMIC_CLIENT_ID:?set COSMIC_CLIENT_ID}:${COSMIC_CLIENT_SECRET:?set COSMIC_CLIENT_SECRET}" \
  --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

The endpoint serves only the stateless protocol revision 2026-07-28. Every POST must use Content-Type: application/json, Accept: application/json, text/event-stream, matching MCP-Protocol-Version and Mcp-Method headers, and the same protocol version in params._meta. For tools/call, Mcp-Name must match params.name: use cosmicephemeris_calculate for calculations or cosmicephemeris_symbolic for supplemental operations. Legacy initialize/session transport is intentionally not enabled: clients supporting only 2025-era initialization cannot connect. OAuth client credentials are not a substitute for an interactive authorization-code/PKCE connector flow.

Missing or mismatched required headers return HTTP 400 with -32020. A matching but unsupported protocol version returns HTTP 400 with -32022 and the supported version list. Update the host's protocol configuration; do not repeatedly retry a calculation.

Discover the server

curl https://api.cosmicephemeris.com/mcp \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --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 'Accept: application/json, text/event-stream' \
  --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. Non-authentication calculation failures are completed tool results with isError: true. A missing, invalid, or expired credential returns an HTTP 401 JSON-RPC error with code -32001; insufficient scope returns an HTTP 403 JSON-RPC error with code -32003. Malformed requests and unsupported methods also return JSON-RPC errors.

The MCP adapter gives the loopback calculation at most 65 seconds. The public proxy's exact /mcp read/send inactivity timeouts are 70 seconds so the edge does not expire before that adapter deadline. These are outer safety bounds, not response-time guarantees; each operation retains its documented 15-, 30-, or 60-second engine deadline.

Call Tarot, readings or supplemental Vedic systems

Use cosmicephemeris_symbolic in both the header and body. This single-card example requires astro:tarot. The other operation/scope pairs are symbolic-reading/astro:symbolic-reading and vedic-systems/astro:vedic-systems; their inputs are defined in the supplemental OpenAPI and interpretation guide.

curl https://api.cosmicephemeris.com/mcp \
  --request POST \
  --header 'X-API-Key: YOUR_SERVER_SIDE_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: tools/call' \
  --header 'Mcp-Name: cosmicephemeris_symbolic' \
  --data '{
    "jsonrpc":"2.0",
    "id":"tarot-1",
    "method":"tools/call",
    "params":{
      "name":"cosmicephemeris_symbolic",
      "arguments":{
        "operation":"tarot",
        "input":{"locale":"en","options":{"spread":"single","theme":"general","reversals":true,"mode":"draw"}}
      },
      "_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientCapabilities":{}
      }
    }
  }'

Each admitted supplemental call uses one standard API credit. Draws can be random; do not automatically retry. MCP does not expose saved account readings or PDF downloads.

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.

Historical dates and tool coverage

MCP forwards the same input as REST without converting dates. Standard civil dates cover 1800–2200. The 77 date-bearing operations accept 1000 BCE (BC)–2500 CE (AD), with an explicit proleptic calendar and, for timed calculations, UT1 or a fixed UT1 offset. Numerology requires an explicit year-digit convention; place search is date-independent. There is no year zero; never infer ancient IANA zones or convert a BCE date into a JavaScript Date. Search windows and per-tool mathematical limits still apply.

For a historical birth-chart call, replace only arguments.input in the example above with:

{
  "date": {"year": 1000, "era": "BCE", "month": 1, "day": 1, "calendar": "proleptic_gregorian"},
  "time": "12:00", "timezone": "UT1", "lat": 28.6, "lon": 77.2
}

The OpenAPI document owns each operation's input schema. The separate cosmicephemeris_symbolic tool uses the supplemental OpenAPI for Tarot, readings and Vedic systems, including named North/South festival calendars. These calls cost one standard credit per admitted attempt and do not access private account readings or PDFs. The saved-reading website screen is retired; existing records and legacy session-only JSON/PDF contracts remain intact, outside MCP. New readings and Tarot draws are stateless API products for your application. Interpretations are clearly labeled AI-assisted symbolic readings, not predictive advice.