The API as an MCP server
The CycleCalcs astronomy API speaks the Model Context Protocol, so Claude and other MCP clients can call it as tools instead of raw HTTP. It is the same API underneath: eleven read-only tools, each backed by one live /v2 endpoint, computed by the same engine and metered by the same keys.
https://www.cyclecalcs.com/mcp
The endpoint is a stateless Streamable HTTP server (POST only, JSON responses). It speaks MCP specification revision 2026-07-28 and the earlier 2025 handshake revisions, so current and older clients both connect.
Authentication and metering
Send a CycleCalcs API key on every request in the Authorization header:
Authorization: Bearer YOUR_RAPIDAPI_KEY
Keys come from the RapidAPI listing; the Basic plan is free. Every tool call is forwarded through the RapidAPI gateway with your key, so usage counts against your plan exactly as a direct REST call would, and your plan's limits apply unchanged. Tool calls without a key are refused with instructions rather than served anonymously, so every invocation stays attributable to a key. The key never goes in the URL.
The key may also be sent as a raw value in an X-Api-Key header, with no Bearer prefix:
X-Api-Key: YOUR_RAPIDAPI_KEY
Both headers are equally supported. The alternative exists because some directories and gateways reserve Authorization for their own sign-in and can only forward a differently named header.
Browsing the server needs no key. initialize and tools/list are answered without one, so a client, an inspector or a directory can connect and read all eleven tool schemas before anyone has signed up for anything. Only invoking a tool requires a key, and the refusal arrives as a normal tool result carrying instructions, not as an HTTP 401 that would drop the connection.
Connecting a client
From Claude Code:
claude mcp add --transport http cyclecalcs https://www.cyclecalcs.com/mcp --header "Authorization: Bearer YOUR_KEY"
In Claude on the web or desktop, add a custom connector with the server URL above and set the Authorization header where your plan offers custom headers (a beta feature on some plans). Any MCP-capable client that can send a request header works the same way; the server needs no session support from the client.
ChatGPT connectors currently authenticate with OAuth or not at all, so this server cannot be added to ChatGPT yet. Developers using the OpenAI Responses API can attach it today by passing the key in the mcp tool's authorization field.
For a start-to-finish walkthrough, with the wire proven by curl before any client is configured and example prompts mapped to the tools they invoke, follow the build guide: give your AI assistant the real sky.
The eleven tools
| Tool | What it answers | Backed by |
|---|---|---|
astro_sky_today | The whole sky for a place and moment: moon, planets up, next eclipse, sun times | /v2/today |
astro_sun | Sunrise, sunset, solar noon, day length and the three twilights, single day or series | /v2/sun |
astro_moon | Moon phase, illumination, distance, libration and next quarters | /v2/moon |
astro_moon_phases | The phase calendar: every new, quarter and full moon with supermoon status and names | /v2/phases |
astro_positions | Exact positions for up to 20 bodies in stated frames, instant or time grid | /v2/positions |
astro_rise_set | Rise, transit and set for one body, with explicit polar status | /v2/rise-set |
astro_eclipses | Solar and lunar eclipses with local circumstances and a visible-from-here answer | /v2/eclipses |
astro_dark_window | The genuinely dark, moonless observing window per night, ranked across nights | /v2/dark-window |
astro_planet_board | All eight planets at a glance: brightness, retrograde state, worth looking tonight | /v2/planet-board |
astro_planet_events | Mercury and Venus apparition events: conjunctions, greatest elongations, peak brightness, transits | /v2/planet-events |
astro_find_place | Place name to coordinates and timezone, or reverse lookup | /v2/places |
Tool results carry the API's own field names, which state their units (_deg, _km, _fraction) and reference frames (equatorial.j2000), plus any warnings the API attached. Errors pass through the API's RFC 9457 problem documents unchanged, including the supported date range of 1700 to 2200.
Rights
Tool results are computed astronomical facts and carry the same rights as the REST API: use them without restriction or attribution. The one exception is unchanged too: place lookups return GeoNames data under CC BY 4.0, and those results include the required credit, which must be preserved when shown.
Building against the REST API instead? Start at the API overview or the endpoint reference. The MCP server adds no endpoints and changes no contracts; it is a protocol adapter in front of the same 30 routes.
All API documentation
- Developer hub: What to build and where every tool lives: API, MCP server, widgets.
- Overview and playground: What the API answers, the plans, and a live try-it panel.
- Endpoint reference: Every route, its parameters and a real captured response.
- Keys and plans: How to get a key, what each plan raises, and how quotas are counted.
- Error codes: The registered problem documents, one entry per code.
- Accuracy and residuals: Measured error against reference ephemerides, and the conventions every response states.
- Versioning policy: What is frozen, what may change, and how a change is announced.
- Status and limits: Rate windows, range caps and the current service position.
- MCP server: The same engine as tools an AI assistant can call directly.
- Version 1 (frozen): The original seven endpoints, still served and never changing shape.
- Terms of use: What you may do with the answers, including in commercial products.