CycleCalcs Astronomy

npx add-mcp 'https://www.cyclecalcs.com/mcp'

La API como servidor MCP

La API de astronomía de CycleCalcs habla el Model Context Protocol, por lo que Claude y otros clientes MCP pueden llamarla como herramientas en lugar de HTTP sin procesar. Es la misma API por debajo: once herramientas de solo lectura, cada una respaldada por un endpoint /v2 en vivo, calculadas por el mismo motor y, con una clave, medidas en los mismos planes.

https://www.cyclecalcs.com/mcp

El endpoint es un servidor HTTP Streamable sin estado (solo POST, respuestas JSON). Habla la revisión 2026-07-28 de la especificación MCP y las revisiones de protocolo de enlace de 2025 anteriores, por lo que tanto los clientes actuales como los antiguos se conectan.

Autenticación y medición

No se necesita clave para comenzar. Las llamadas a herramientas sin clave se atienden desde la API sin clave, hasta 50 llamadas al día por dirección de red, contadas en un período móvil de 24 horas. Quienes comparten una dirección, como una red de oficina o una aplicación de IA cuyos servidores hacen las llamadas por todos sus usuarios, comparten una sola asignación hasta que se conectan con una clave. Un inicio de sesión sin clave se cuenta por sí mismo y contra su dirección, por lo que nunca se suma a lo que le queda a la dirección. El conteo lo mantiene cada instancia de servidor en ejecución, por lo que es aproximado.

Pasada la asignación, una llamada sin clave se responde con HTTP 401 y un desafío de inicio de sesión, que los clientes MCP que siguen la especificación de autorización responden abriendo un inicio de sesión. Un cliente que no puede iniciar sesión envía una clave en un encabezado, como se muestra a continuación. Un cliente que ya inició sesión sin clave recibe un resultado de herramienta que indica cómo continuar con una.

Para que las llamadas a herramientas se midan en tu propio plan, envía una clave de API de CycleCalcs en cada solicitud en el encabezado Authorization:

Authorization: Bearer YOUR_RAPIDAPI_KEY

Las claves provienen del listado de RapidAPI; el plan Basic es gratuito. Una llamada realizada con una clave se reenvía a través de la puerta de enlace de RapidAPI con esa clave, por lo que cuenta contra tu plan exactamente como lo haría una llamada REST directa, y los límites de tu plan se aplican sin cambios. La clave nunca va en la URL.

La clave también se puede enviar como un valor sin procesar en un encabezado X-Api-Key, sin prefijo Bearer:

X-Api-Key: YOUR_RAPIDAPI_KEY

Ambos encabezados son igualmente compatibles. La alternativa existe porque algunos directorios y puertas de enlace reservan Authorization para su propio inicio de sesión y solo pueden reenviar un encabezado con un nombre diferente.

Navegar por el servidor no requiere clave. initialize y tools/list se responden sin una, por lo que un cliente, un inspector o un directorio pueden conectarse y leer los once esquemas de herramientas antes de que alguien se haya registrado en algo.

Conectar un cliente

Claude y ChatGPT. Agrega la URL del servidor anterior como conector personalizado. Ambas aplicaciones llaman al servidor desde sus propios servidores, por lo que sin una clave un conector comparte la asignación sin clave de esas direcciones con los otros usuarios de la aplicación, y una clave es lo que mantiene sus llamadas en funcionamiento. Si la aplicación abre la página de inicio de sesión, ingresa la clave allí: las llamadas se miden en tu plan, y verificar la clave usa una solicitud del mismo. Para evitar que una clave se use aquí, regenérala en tu panel de RapidAPI.

Claude Code, con una clave:

claude mcp add --transport http cyclecalcs https://www.cyclecalcs.com/mcp --header "Authorization: Bearer YOUR_KEY"

Omite --header para comenzar sin clave. Cualquier cliente compatible con MCP que pueda enviar un encabezado de solicitud funciona de la misma manera; el servidor no requiere soporte de sesión del cliente.

Para autores de clientes OAuth. El descubrimiento comienza en /.well-known/oauth-protected-resource/mcp. El servidor admite OAuth 2.1 con PKCE S256, registro dinámico de clientes y documentos de metadatos de ID de cliente, solo para clientes públicos. Pasada la asignación, un cliente que inició sesión sin clave, y una llamada que lleva los metadatos de solicitud openai/ del SDK de OpenAI Apps, reciben el desafío dentro del resultado de la herramienta en lugar de un 401: _meta["mcp/www_authenticate"], con error="insufficient_scope", que es la forma que el SDK documenta para abrir la vinculación de cuentas.

Para un recorrido de principio a fin, con el cable probado por curl antes de configurar cualquier cliente y ejemplos de indicaciones asignados a las herramientas que invocan, sigue la guía de construcción: dale a tu asistente de IA el cielo real.

Las once herramientas

Herramienta	Qué responde	Respaldada por
astro_sky_today	Todo el cielo para un lugar y momento: luna, planetas visibles, próximo eclipse, horas solares	/v2/today
astro_sun	Amanecer, atardecer, mediodía solar, duración del día y los tres crepúsculos, día único o serie	/v2/sun
astro_moon	Fase lunar, iluminación, distancia, libración y próximos cuartos	/v2/moon
astro_moon_phases	El calendario de fases: cada luna nueva, cuarto y llena con estado de superluna y nombres	/v2/phases
astro_positions	Posiciones exactas para hasta 20 cuerpos en marcos declarados, instantáneo o cuadrícula de tiempo	/v2/positions
astro_rise_set	Salida, tránsito y puesta para un cuerpo, con estado polar explícito	/v2/rise-set
astro_eclipses	Eclipses solares y lunares con circunstancias locales y una respuesta de visible desde aquí	/v2/eclipses
astro_dark_window	La ventana de observación genuinamente oscura y sin luna por noche, clasificada entre noches	/v2/dark-window
astro_planet_board	Los ocho planetas de un vistazo: brillo, estado retrógrado, si vale la pena mirar esta noche	/v2/planet-board
astro_planet_events	Eventos planetarios: apariciones de Mercurio y Venus, conjunciones de Marte a Neptuno con el Sol, cuadraturas y oposiciones, y entradas en constelaciones	/v2/planet-events
astro_find_place	Nombre de lugar a coordenadas y zona horaria, o búsqueda inversa	/v2/places

Los resultados de las herramientas llevan los nombres de campo propios de la API, que indican sus unidades (_deg, _km, _fraction) y marcos de referencia (equatorial.j2000), además de cualquier advertencia que la API adjunte. Los errores pasan a través de los documentos de problema RFC 9457 de la API sin cambios, incluido el rango de fechas compatible de 1700 a 2200.

Qué rutas REST alcanzan las herramientas

Las llamadas a herramientas MCP funcionan sin clave hasta 50 llamadas al día por dirección de red, y con una clave de RapidAPI más allá de eso. La API REST no necesita ninguna: cada ruta a continuación responde una solicitud HTTPS simple en el nivel Basic gratuito. Un asistente limitado a MCP solo puede alcanzar las rutas que tienen una herramienta.

De las rutas de datos a continuación, 11 son alcanzadas por una herramienta y las otras 15 son solo REST. La tabla omite /v2, /v2/conventions, /v2/enums y /v2/attribution, que describen la API en sí misma en lugar del cielo.

Ruta REST	Herramienta MCP
/v2/positions	astro_positions
/v2/rise-set	astro_rise_set
/v2/sun	astro_sun
/v2/moon	astro_moon
/v2/time	Solo REST
/v2/seasons	Solo REST
/v2/apsides	Solo REST
/v2/moon-nodes	Solo REST
/v2/eclipses	astro_eclipses
/v2/planet-board	astro_planet_board
/v2/retrogrades	Solo REST
/v2/conjunctions	Solo REST
/v2/separation	Solo REST
/v2/rarity	Solo REST
/v2/cycles	Solo REST
/v2/twilight	Solo REST
/v2/dark-window	astro_dark_window
/v2/sidereal-time	Solo REST
/v2/equation-of-time	Solo REST
/v2/libration	Solo REST
/v2/jupiter-moons	Solo REST
/v2/sky-quality	Solo REST
/v2/places	astro_find_place
/v2/phases	astro_moon_phases
/v2/planet-events	astro_planet_events
/v2/today	astro_sky_today

Derechos

Los resultados de las herramientas son hechos astronómicos calculados y llevan los mismos derechos que la API REST: úsalos sin restricción ni atribución. La única excepción también es la misma: las búsquedas de lugares devuelven datos de GeoNames bajo CC BY 4.0, y esos resultados incluyen el crédito requerido, que debe conservarse al mostrarse.

¿Construyendo contra la API REST en su lugar? Comienza en la descripción general de la API o en la referencia de endpoints. El servidor MCP no agrega endpoints ni cambia contratos; es un adaptador de protocolo frente a la misma API, y la tabla de cobertura muestra qué rutas alcanza.

Toda la documentación de la API

• Centro de desarrolladores: Qué construir y dónde vive cada herramienta: API, servidor MCP, widgets.
• Descripción general y área de pruebas: Qué responde la API, los planes y un panel de prueba en vivo.
• Referencia de endpoints: Cada ruta, sus parámetros y una respuesta real capturada.
• Claves y planes: Cómo obtener una clave, qué eleva cada plan y cómo se cuentan las cuotas.
• Códigos de error: Los documentos de problema registrados, una entrada por código.
• Precisión y residuales: Error medido contra efemérides de referencia y las convenciones que cada respuesta declara.
• Política de versionado: Qué está congelado, qué puede cambiar y cómo se anuncia un cambio.
• Estado y límites: Ventanas de tasa, límites de rango y la posición actual del servicio.
• Servidor MCP: El mismo motor como herramientas que un asistente de IA puede llamar directamente.
• Versión 1 (congelada): Los siete endpoints originales, aún servidos y que nunca cambian de forma.
• Términos de uso: Qué puedes hacer con las respuestas, incluso en productos comerciales.