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, with a key, metered on the same plans.
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
No key is needed to start. Tool calls without a key are served from the keyless API, up to 50 calls a day per network address, counted over a rolling 24 hours. Callers who share an address, such as an office network or an AI app whose servers make the calls for all its users, share one allowance until they connect with a key. A sign-in without a key is counted on its own and against its address, so it never adds to what the address has left. The count is kept by each running server instance, so it is approximate.
Past the allowance, a keyless call is answered with HTTP 401 and a sign-in challenge, which MCP clients that follow the authorization spec answer by opening a sign-in. A client that cannot sign in sends a key in a header instead, as below. A client already signed in without a key gets HTTP 403 with error="insufficient_scope", the spec's signal to authorize again; the sign-in page then offers the key field.
To have tool calls metered on your own RapidAPI plan, send your RapidAPI key on every request in the Authorization header:
Authorization: Bearer YOUR_RAPIDAPI_KEY
Keys come from the RapidAPI listing; the Basic plan is free. A call made with a key is forwarded through the RapidAPI gateway with that key, so it counts against your plan exactly as a direct REST call would, and your plan's limits apply unchanged. 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.
Connecting a client
Claude and ChatGPT. Add the server URL above as a custom connector. Both apps call the server from their own servers, so without a key a connector shares the keyless allowance of those addresses with the app's other users, and a key is what keeps its calls going. If the app opens the sign-in page, enter the key there: calls are then metered on your plan, and checking the key uses one request of it. To stop a key being used here, regenerate it in your RapidAPI dashboard.
Claude Code, with a key:
claude mcp add --transport http cyclecalcs https://www.cyclecalcs.com/mcp --header "Authorization: Bearer YOUR_KEY"
Leave out --header to start keyless. Any MCP-capable client that can send a request header works the same way; the server needs no session support from the client.
For OAuth client authors. Discovery starts at /.well-known/. The server supports OAuth 2.1 with PKCE S256, dynamic client registration and client ID metadata documents, for public clients only. Past the allowance, a client signed in without a key gets HTTP 403 whose WWW-Authenticate header carries error="insufficient_scope" with the same resource_metadata and scope as the 401, the spec's step-up signal. A call carrying the OpenAI Apps SDK's openai/ (or the older webplus/) request metadata gets the same challenge inside the tool result instead of a 401 or 403: _meta["mcp/www_authenticate"], which is the form that SDK documents for opening account linking. Every tool declares securitySchemes (noauth, and oauth2 with scope astronomy.read) at the top level of the tool and again in its _meta.
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.
Example prompts
Once the server is connected, ask in plain words and the assistant picks the tool. Each of these is answered by one tool:
| Ask | Tool | What comes back |
|---|---|---|
| What is in the sky tonight from Lisbon? | astro_sky_today | The Moon's phase, the planets that are up, the next eclipse and the sun times, with the GeoNames credit for the place |
| When do sunrise, sunset and astronomical twilight happen in Denver on 21 December 2026? | astro_sun | Each time for that date, plus the length of the day |
| When is the next solar eclipse visible from Madrid, and what are the local contact times? | astro_eclipses | The eclipse, whether it can be seen from there, and its contact times |
The build guide has more, each mapped to the tool it invokes.
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 | Planet events: Mercury and Venus apparitions, Mars to Neptune conjunctions with the Sun, quadratures and oppositions, and constellation entries | /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.
Which REST routes the tools reach
MCP tool calls work without a key up to 50 calls a day per network address, and with a RapidAPI key past that. The REST API needs none: each route below answers a plain HTTPS request at the free Basic tier. An assistant limited to MCP can reach only the routes that have a tool.
Of the data routes below, 11 are reached by a tool and the other 15 are REST only. The table leaves out /v2, /v2/conventions, /v2/enums and /v2/attribution, which describe the API itself rather than the sky.
| REST route | MCP tool |
|---|---|
/v2/positions | astro_positions |
/v2/rise-set | astro_rise_set |
/v2/sun | astro_sun |
/v2/moon | astro_moon |
/v2/time | REST only |
/v2/seasons | REST only |
/v2/apsides | REST only |
/v2/moon-nodes | REST only |
/v2/eclipses | astro_eclipses |
/v2/planet-board | astro_planet_board |
/v2/retrogrades | REST only |
/v2/conjunctions | REST only |
/v2/separation | REST only |
/v2/rarity | REST only |
/v2/cycles | REST only |
/v2/twilight | REST only |
/v2/dark-window | astro_dark_window |
/v2/sidereal-time | REST only |
/v2/equation-of-time | REST only |
/v2/libration | REST only |
/v2/jupiter-moons | REST only |
/v2/sky-quality | REST only |
/v2/places | astro_find_place |
/v2/phases | astro_moon_phases |
/v2/planet-events | astro_planet_events |
/v2/today | astro_sky_today |
Troubleshooting
The tools do not appear. Check that the server URL is exactly https://www.cyclecalcs.com/mcp, with the www. Listing the tools needs no key and no sign-in, so a connection that lists nothing points to the URL or the network. An account has nothing to do with it.
A Connect or sign-in card appears. The keyless allowance for the address the calls come from is used up, or a sign-in without a key has run into it. Open the card, paste a RapidAPI key into RapidAPI key (optional) on the CycleCalcs page and choose Connect with this key, then ask again if the answer does not arrive on its own. Continue without a key does not help here, because a sign-in without a key shares the same allowance.
keyless_cap_reached. Keyless calls are served up to 50 calls a day per network address, and an AI app that calls from its own servers shares that allowance among all its users. The message says when the next call frees up. To keep going now, sign in with a key, or send one in a header as above; a key in a header is read only when no sign-in is attached.
key_rejected. RapidAPI did not accept the key. Check that it was pasted whole and that the RapidAPI account is subscribed to the CycleCalcs Astronomy API (the Basic plan is free). A key regenerated in the RapidAPI dashboard stops working everywhere it was used, including inside an earlier sign-in, and the server keeps refusing the old one until the new key is entered. A client that sends the key in a header replaces the header value. A client that signed in through the sign-in page needs a fresh sign-in: if the app offers no way to sign in again, disconnect the server in the app and add it again, then enter the new key when the sign-in page next appears.
quota_exhausted. The key's plan has used its quota, or calls arrived faster than the plan's rate allows. Wait for the window to reset (retry_after_seconds, when present, says how long) or move to a larger plan on RapidAPI.
DATE_OUT_OF_RANGE. Dates run from 1700 to 2200, because the ephemeris is not reliable outside that range. Ask about a date inside it; the error names the supported range.
LOCATION_REQUIRED. The tool needs a place. Name one in the question ("from Lisbon") or give coordinates ("at 38.72, -9.14"), and add the country when several places share a city's name.
Security reports
To report a security vulnerability in the MCP server, its sign-in pages, the API or any page on cyclecalcs.com, email info@cyclecalcs.com with "Security report" in the subject. Say what you found, where, and the steps that show it. Test only with your own keys and sign-ins, do not load-test the service, and allow time for a fix before you publish details. The same contact is published for tools at /.well-known/security.txt, in the RFC 9116 format.
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 API, and the coverage table shows which routes it reaches.
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.