Servidor MCP: Utilize a AstroAPI a partir de Assistentes de IA

A AstroAPI disponibiliza um servidor Model Context Protocol (MCP) alojado. Ligue-o a um assistente de IA como o Claude Code, o Claude Desktop ou o Cursor, e o assistente pode chamar a AstroAPI diretamente — pesquisar locais de nascimento, calcular mapas e explicar os resultados em linguagem simples.

Esta é também a forma mais rápida de construir uma integração: ligue o servidor MCP ao seu assistente de programação com IA e peça-lhe que escreva o código de integração por si. O assistente pode fazer chamadas reais à API enquanto trabalha, pelo que vê respostas reais em vez de adivinhar.

Sem necessidade de código

Depois de ligado, pode simplesmente pedir ao seu assistente coisas como "Calcula o mapa natal de alguém nascido a 15 de junho de 1990 às 14h30 em Amesterdão" — o assistente resolve a localização, chama a API e resume o resultado.

---

Endpoint

https://mcp.astroapi.cloud/mcp

• Transporte: Streamable HTTP
• Autenticação: a sua chave AstroAPI habitual, enviada no cabeçalho X-Api-Key
• Os módulos, limites de taxa e quotas da sua subscrição aplicam-se exatamente como nas chamadas diretas à API.

Pode criar uma chave de API no dashboard em API Keys. Consulte Autenticação para mais detalhes.

---

Ligar o Claude Code

Execute isto uma vez no seu terminal:

claude mcp add --transport http astroapi https://mcp.astroapi.cloud/mcp \
  --header "X-Api-Key: YOUR_API_KEY"

Depois, basta pedir ao Claude Code que utilize a AstroAPI — por exemplo: "Usa as ferramentas astroapi para calcular um mapa natal para 1990-06-15 14:30 em Amesterdão e constrói-me um componente React que o apresente."

Ligar o Cursor

Adicione isto a .cursor/mcp.json no seu projeto (ou a ~/.cursor/mcp.json globalmente):

{
  "mcpServers": {
    "astroapi": {
      "url": "https://mcp.astroapi.cloud/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Ligar outros clientes MCP

Qualquer cliente que suporte MCP sobre Streamable HTTP com cabeçalhos personalizados funciona. Configure:

Definição	Valor
URL	https://mcp.astroapi.cloud/mcp
Transporte	Streamable HTTP
Cabeçalho	X-Api-Key: YOUR_API_KEY

Clientes alojados sem cabeçalhos personalizados

Alguns clientes alojados (como os conectores web do claude.ai) não conseguem enviar cabeçalhos personalizados e exigem OAuth. O suporte para OAuth está no roadmap; por agora, utilize um cliente que suporte cabeçalhos personalizados, como o Claude Code, o Claude Desktop ou o Cursor.

---

Ferramentas Disponíveis

Ferramenta	O que faz
astro_resolve_place	Pesquisa um nome de local e devolve as coordenadas e o fuso horário IANA. Os assistentes são instruídos a chamar esta ferramenta primeiro, para que nunca adivinhem coordenadas.
astro_natal_chart	Calcula um mapa natal (pontos, casas, aspetos), opcionalmente com textos de interpretação, e devolve um resumo compacto e legível.

Mais ferramentas (trânsitos, sinastria, compatibilidade, fases da lua, imagens de mapas e outras) estão a caminho. A disponibilidade das ferramentas segue os módulos da sua subscrição: uma ferramenta que o seu plano não inclui devolve uma mensagem clara em vez de dados.

---

Sessão de Exemplo

Uma conversa com um assistente ligado pode ter este aspeto:

Você: Qual é o signo solar e o ascendente de alguém nascido a 3 de março de 1985 às 6h45 em Barcelona?

Assistente: chama astro_resolve_place com "Barcelona", depois astro_natal_chart com as coordenadas e o fuso horário resolvidos — O Sol está em Peixes a 12°41′ na casa 1, e o Ascendente é Aquário 28°10′ …

O assistente trata da geocodificação, da conversão de fuso horário e da chamada à API — as coisas que normalmente correm mal ao introduzir dados de nascimento à mão.

---

Próximos Passos

• Autenticação — criar e gerir chaves de API
• Primeiros Passos — os fundamentos da API por trás destas ferramentas
• Mapas Natais — o que o cálculo natal devolve