MCP Setup

caelus-mcp exposes the engine over the Model Context Protocol. Positions are computed by the engine on each call, never recalled from training data, so every answer is deterministic.

There are two ways to connect, with the same nine tools either way:

• Hosted (Streamable HTTP) — point your client at https://www.ephemengine.com/api/mcp. Nothing to install.
• Local (stdio) — run npx -y caelus-mcp. Best for offline use, version pinning, or air-gapped setups.

Hosted endpoint (no install)

The tools are served over MCP Streamable HTTP at https://www.ephemengine.com/api/mcp. The endpoint is stateless: each request is self-contained, so there is no session to manage. Positions are identical to the stdio server.

{
"mcpServers": {
  "caelus": {
    "url": "https://www.ephemengine.com/api/mcp"
  }
}
}

Run it locally

The published binary runs straight from npm — no global install:

npx -y caelus-mcp

It waits for an MCP client to speak to it over stdio, so an empty terminal is expected. Wire it into a client below instead of running it by hand.

Configure your client

Every client points at the same command (npx -y caelus-mcp); only the config file and key differ.

{
"mcpServers": {
  "caelus": {
    "command": "npx",
    "args": ["-y", "caelus-mcp"]
  }
}
}

Verify the tools appeared

After the client reloads, it should list nine tools. Ask it to enumerate them, or check the client's MCP panel:

natal_chart, current_sky, transits, synastry, find_aspect_dates, rectification_grid, sky_events (rise/set, phases, stations, zodiac crossings, solar and lunar eclipses), planetary_hours, and void_of_course.

natal_chart and current_sky also tag each body with its solar phase (cazimi, combust, under the beams) and each aspect as applying or separating.

If you see all nine, the server is wired correctly. The server also exposes two resources — caelus://glossary (aspect angles and orbs, signs, bodies, house systems, essential dignities) and caelus://accuracy (the validation table) — and a prompt, rectification_session, a guided flow around rectification_grid and find_aspect_dates.

A natal-chart call returns structured positions, not prose:

{
"utc": "1990-06-10T14:30:00Z",
"houses": "placidus",
"bodies": {
  "sun":  { "lon": 79.45,  "pos": "19°27'Gem", "house": 11, "speed": 0.96 },
  "moon": { "lon": 283.28, "pos": "13°17'Cap", "house": 6,  "speed": 12.19 },
  "saturn": { "lon": 294.31, "pos": "24°18'Cap", "house": 6, "rx": true, "speed": -0.05 }
}
}

Example prompts

• "Natal chart: born June 10 1990, 2:30pm, Tampa FL."
• "When is Saturn square my natal Moon in the next two years?"
• "Compare my chart with my partner's."
• "Next solar eclipse? Lunar eclipses in 2026?"

Troubleshooting

• npx not found / server never starts. GUI clients (Claude Desktop, Cursor) do not inherit your shell PATH, so a node/npx installed via nvm or Homebrew may be invisible. Use the absolute path as command (find it with which npx), or install Node where the client can see it. Node 18+ is required.
• Tools don't show up. Most clients only read MCP config on a full restart — quit completely (not just close the window) and reopen. Confirm the JSON parses (a trailing comma is the usual culprit).
• First call is slow. npx downloads the package on first run; it is cached afterward. Pinning a version (below) avoids surprise re-downloads.

Version pinning for production

npx -y caelus-mcp always resolves the latest release. Pin an exact version so behaviour is reproducible and the four packages stay in lockstep:

{
"mcpServers": {
  "caelus": {
    "command": "npx",
    "args": ["-y", "caelus-mcp@0.8.0"]
  }
}
}

Agent-oriented docs live at llms.txt. See Architecture for where MCP fits in an end-to-end app.