CycleCalcs Astronomy

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

A API como um servidor MCP

A API de astronomia CycleCalcs fala o Model Context Protocol, então o Claude e outros clientes MCP podem chamá-la como ferramentas em vez de HTTP bruto. É a mesma API por baixo: onze ferramentas somente leitura, cada uma apoiada por um endpoint /v2 ativo, calculadas pelo mesmo mecanismo e, com uma chave, medidas nos mesmos planos.

https://www.cyclecalcs.com/mcp

O endpoint é um servidor HTTP Streamable sem estado (somente POST, respostas JSON). Ele fala a revisão 2026-07-28 da especificação MCP e as revisões de handshake anteriores de 2025, então clientes atuais e antigos ambos se conectam.

Autenticação e medição

Nenhuma chave é necessária para começar. Chamadas de ferramentas sem chave são atendidas pela API sem chave, até 50 chamadas por dia por endereço de rede, contadas em uma janela contínua de 24 horas. Chamadores que compartilham um endereço, como uma rede de escritório ou um aplicativo de IA cujos servidores fazem as chamadas para todos os seus usuários, compartilham uma cota até se conectarem com uma chave. Um login sem chave é contado por conta própria e contra seu endereço, então nunca adiciona ao que o endereço ainda tem. A contagem é mantida por cada instância de servidor em execução, então é aproximada.

Além da cota, uma chamada sem chave é respondida com HTTP 401 e um desafio de login, que clientes MCP que seguem a especificação de autorização respondem abrindo um login. Um cliente que não pode fazer login envia uma chave em um cabeçalho, como abaixo. Um cliente já conectado sem chave recebe um resultado de ferramenta dizendo como continuar com uma.

Para que as chamadas de ferramentas sejam medidas no seu próprio plano, envie uma chave de API CycleCalcs em cada requisição no cabeçalho Authorization:

Authorization: Bearer YOUR_RAPIDAPI_KEY

As chaves vêm da listagem RapidAPI; o plano Basic é gratuito. Uma chamada feita com uma chave é encaminhada através do gateway RapidAPI com essa chave, então conta contra o seu plano exatamente como uma chamada REST direta contaria, e os limites do seu plano se aplicam sem alterações. A chave nunca vai na URL.

A chave também pode ser enviada como um valor bruto em um cabeçalho X-Api-Key, sem o prefixo Bearer:

X-Api-Key: YOUR_RAPIDAPI_KEY

Ambos os cabeçalhos são igualmente suportados. A alternativa existe porque alguns diretórios e gateways reservam Authorization para seu próprio login e só podem encaminhar um cabeçalho com nome diferente.

Navegar no servidor não precisa de chave. initialize e tools/list são respondidos sem uma, então um cliente, um inspetor ou um diretório pode se conectar e ler todos os onze esquemas de ferramentas antes de qualquer um se cadastrar em qualquer coisa.

Conectando um cliente

Claude e ChatGPT. Adicione a URL do servidor acima como um conector personalizado. Ambos os aplicativos chamam o servidor de seus próprios servidores, então sem uma chave um conector compartilha a cota sem chave desses endereços com os outros usuários do aplicativo, e uma chave é o que mantém suas chamadas funcionando. Se o aplicativo abrir a página de login, insira a chave lá: as chamadas são então medidas no seu plano, e verificar a chave usa uma requisição dele. Para parar o uso de uma chave aqui, regenere-a no seu painel RapidAPI.

Claude Code, com uma chave:

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

Deixe de fora --header para começar sem chave. Qualquer cliente capaz de MCP que possa enviar um cabeçalho de requisição funciona da mesma maneira; o servidor não precisa de suporte a sessão do cliente.

Para autores de clientes OAuth. A descoberta começa em /.well-known/oauth-protected-resource/mcp. O servidor suporta OAuth 2.1 com PKCE S256, registro dinâmico de clientes e documentos de metadados de ID de cliente, apenas para clientes públicos. Além da cota, um cliente conectado sem chave, e uma chamada carregando os metadados de requisição openai/ do SDK de Aplicativos OpenAI, recebem o desafio dentro do resultado da ferramenta em vez de um 401: _meta["mcp/www_authenticate"], com error="insufficient_scope", que é a forma que o SDK documenta para abrir a vinculação de conta.

Para um passo a passo completo, com o wire comprovado por curl antes de qualquer cliente ser configurado e exemplos de prompts mapeados para as ferramentas que eles invocam, siga o guia de construção: dê ao seu assistente de IA o céu real.

As onze ferramentas

Ferramenta	O que responde	Apoiada por
astro_sky_today	O céu inteiro para um lugar e momento: lua, planetas visíveis, próximo eclipse, horários do sol	/v2/today
astro_sun	Nascer do sol, pôr do sol, meio-dia solar, duração do dia e os três crepúsculos, dia único ou série	/v2/sun
astro_moon	Fase da lua, iluminação, distância, libração e próximos quartos	/v2/moon
astro_moon_phases	O calendário de fases: cada lua nova, quarto e lua cheia com status de superlua e nomes	/v2/phases
astro_positions	Posições exatas para até 20 corpos em quadros declarados, instantâneo ou grade de tempo	/v2/positions
astro_rise_set	Nascer, trânsito e pôr para um corpo, com status polar explícito	/v2/rise-set
astro_eclipses	Eclipses solares e lunares com circunstâncias locais e uma resposta de visível-daqui	/v2/eclipses
astro_dark_window	A janela de observação genuinamente escura e sem lua por noite, classificada entre noites	/v2/dark-window
astro_planet_board	Todos os oito planetas de relance: brilho, estado retrógrado, vale a pena olhar hoje à noite	/v2/planet-board
astro_planet_events	Eventos planetários: aparições de Mercúrio e Vênus, conjunções de Marte a Netuno com o Sol, quadraturas e oposições, e entradas em constelações	/v2/planet-events
astro_find_place	Nome do lugar para coordenadas e fuso horário, ou busca reversa	/v2/places

Os resultados das ferramentas carregam os nomes de campos da própria API, que declaram suas unidades (_deg, _km, _fraction) e quadros de referência (equatorial.j2000), além de quaisquer avisos que a API anexou. Erros passam pelos documentos de problema RFC 9457 da API sem alterações, incluindo o intervalo de datas suportado de 1700 a 2200.

Quais rotas REST as ferramentas alcançam

Chamadas de ferramentas MCP funcionam sem chave até 50 chamadas por dia por endereço de rede, e com uma chave RapidAPI além disso. A API REST não precisa de nenhuma: cada rota abaixo responde a uma requisição HTTPS simples no nível gratuito Basic. Um assistente limitado a MCP só pode alcançar as rotas que têm uma ferramenta.

Das rotas de dados abaixo, 11 são alcançadas por uma ferramenta e as outras 15 são somente REST. A tabela deixa de fora /v2, /v2/conventions, /v2/enums e /v2/attribution, que descrevem a própria API em vez do céu.

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

Direitos

Os resultados das ferramentas são fatos astronômicos computados e carregam os mesmos direitos que a API REST: use-os sem restrição ou atribuição. A única exceção também não muda: buscas de lugares retornam dados GeoNames sob CC BY 4.0, e esses resultados incluem o crédito exigido, que deve ser preservado quando exibido.

Construindo contra a API REST em vez disso? Comece na visão geral da API ou na referência de endpoints. O servidor MCP não adiciona endpoints e não muda contratos; é um adaptador de protocolo na frente da mesma API, e a tabela de cobertura mostra quais rotas ele alcança.

Toda a documentação da API

• Hub do desenvolvedor: O que construir e onde cada ferramenta vive: API, servidor MCP, widgets.
• Visão geral e playground: O que a API responde, os planos e um painel de teste ao vivo.
• Referência de endpoints: Cada rota, seus parâmetros e uma resposta real capturada.
• Chaves e planos: Como obter uma chave, o que cada plano aumenta e como as cotas são contadas.
• Códigos de erro: Os documentos de problema registrados, uma entrada por código.
• Precisão e resíduos: Erro medido contra efemérides de referência e as convenções que cada resposta declara.
• Política de versionamento: O que está congelado, o que pode mudar e como uma mudança é anunciada.
• Status e limites: Janelas de taxa, limites de intervalo e a posição atual do serviço.
• Servidor MCP: O mesmo mecanismo como ferramentas que um assistente de IA pode chamar diretamente.
• Versão 1 (congelada): Os sete endpoints originais, ainda servidos e nunca mudando de forma.
• Termos de uso: O que você pode fazer com as respostas, incluindo em produtos comerciais.