MCP — conexão Claude / Cursor

O servidor Model Context Protocol (MCP) AstroWay expõe todos os 723 endpoints como ferramentas para agentes de IA. Dois modos — ambos suportados nativamente por todos os clientes compatíveis com MCP.

Modo	URL / Comando	Quando escolher
Hosted HTTP	https://mcp.astroway.info/mcp	Usuários do Claude Web (claude.ai no navegador), Claude Desktop / Cursor / Code para iniciantes sem npm, ou quando queres zero-install
Stdio (npm)	npx @astroway/mcp	Usuários avançados do Cursor, desenvolvimento local, preocupados com privacidade (a chave nunca sai da tua máquina), prontos para offline

O endpoint hosted e o pacote npm usam o mesmo catálogo de ferramentas (gerado a partir do mesmo /v1/openapi.json). Autenticação: a mesma chave de API aw_test_* / aw_live_* — no hosted é enviada via Authorization: Bearer … no header, no stdio é passada pela variável de ambiente ASTROWAY_API_KEY.

Source: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp · hosted: mcp.astroway.info/health

Hosted (mcp.astroway.info) — zero install

Começa rápido sem npm — escolhe o teu cliente. Antes de instalar, obtém a tua chave em api.astroway.info/dashboard/sign-up (10 000 créditos/mês grátis).

Cursor (one-click)

Clica no botão — o Cursor abrirá, pedirá confirmação e adicionará automaticamente a entrada:

Install in Cursor →

Passo 2 obrigatório — caso contrário não funciona

O Cursor não substitui segredos no deeplink — no ~/.cursor/mcp.json será gravado o literal Bearer YOUR_API_KEY, ao qual o servidor responde com 403 invalid_format.

Após clicares no botão:

1. Cursor Settings (⚙️ canto superior direito) → Tools & MCP → localiza astroway-hosted na lista.
2. Clica nos três pontos (⋯) ao lado do servidor → Edit configuration.
3. No campo Authorization, substitui Bearer YOUR_API_KEY por Bearer aw_test_… (ou aw_live_…) — a tua chave real obtida no Dashboard.
4. Guarda → abre novamente a lista de MCP → verifica que o estado é enabled + ponto verde + contador 630 tools enabled.

Alternativamente, edita diretamente o ficheiro: ~/.cursor/mcp.json (headers.Authorization).

Nota

O Cursor impõe um limite no comprimento dos nomes: server_name:tool_name ≤ 60 caracteres. Cerca de 50 dos 630 instrumentos (grupos hellenistic_brennan_*, psychological_modern_*, numerology_kabbalistic_strict_*) são filtrados pelo Cursor e ficarão indisponíveis para o LLM. Os restantes ~580 funcionam. No Claude Desktop não existe este limite — catálogo completo.

Claude Desktop (UI flow)

Sem edição de JSON. Em qualquer chat do Claude Desktop:

1. Clica no + à esquerda do campo de entrada → no menu, escolhe “Add connector”.
2. Na janela de diálogo, seleciona “Add custom connector”.
3. Name: astroway-hosted
4. URL: https://mcp.astroway.info/mcp
5. Expande “Advanced settings” → em “Custom headers”, adiciona:
   • Key: Authorization
   • Value: Bearer aw_live_... (a tua chave)
6. Add → localiza astroway-hosted na lista de Connectors, ativa o interruptor.

Não é necessário reiniciar o Claude Desktop. Clica no + num novo chat — na lista de Connectors aparecerá astroway-hosted com todas as 630 ferramentas + 12 prompts + 14 recursos.

JSON config (manual)

Para Cline / Continue / Windsurf ou versões antigas do Claude Desktop / Cursor:

{
  "mcpServers": {
    "astroway-hosted": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": {
        "Authorization": "Bearer aw_live_..."
      }
    }
  }
}

Caminhos para os ficheiros de configuração:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json (global) ou .cursor/mcp.json (no workspace)
• Cline (VS Code): .cline/mcp.json no workspace
• Continue: ~/.continue/config.json (bloco mcpServers)
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Após editar, reinicia completamente o cliente (Cmd+Q → abrir novamente).

Verificação

curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}

No cliente — pede: “List 5 AstroWay tool names from astroway-hosted”. Deve retornar nomes como astroway_western_chart, astroway_horoscope_daily, astroway_vedic_panchang_full, …

Rate limits

O endpoint hosted é protegido por um limite de 3 níveis: Cloudflare DDoS layer + nginx 120 req/min/IP + bucket em memória 60/60s/(IP+key). Os clientes MCP reais (Claude Desktop, Cursor) não chegam perto destes limites — não fazem pedidos em rajada. Se a tua automação / CI precisar de > 120 req/min — usa o modo stdio (sem limites, vai diretamente para api.astroway.info/v1/* com o teu rate-limit do teu plano).

E se o mcp.astroway.info estiver temporariamente indisponível

Se o endpoint hosted retornar 5xx, o cliente MCP verá um erro ao chamar tools/list. Isto não afeta os clientes stdio — eles executam o pacote npm local, que se liga diretamente ao api.astroway.info/v1/* sem a camada hosted intermédia.

Fallback para integrações críticas: adiciona um segundo servidor MCP na configuração em modo stdio — o cliente usará automaticamente este se o hosted não responder ao tools/list:

{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    },
    "astroway-fallback": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

O uptime real do endpoint hosted pode ser consultado em status.astroway.info. Incidentes com duração superior a 5 minutos são publicados como postmortem em até 5 dias úteis (conforme /sla/).

Stdio (npm) — para desenvolvimento local

O pacote @astroway/mcp é um pacote npm que é executado localmente como subprocesso. Um único pacote npm, integração nativa com Claude Desktop, Cursor e qualquer cliente compatível com MCP.

Como funciona

A lista de ferramentas é gerada no momento da compilação a partir da especificação OpenAPI em tempo real (api.astroway.info/v1/openapi.json). Cada lançamento do pacote capta automaticamente todos os novos endpoints — não é necessário manter manualmente.

Cada endpoint torna-se numa ferramenta do tipo:

• tools/list retorna a descrição e o schema de entrada (com exemplo do corpo da requisição)
• tools/call faz um POST HTTP para https://api.astroway.info/v1/<path> com a tua ASTROWAY_API_KEY
• A resposta é devolvida ao agente como JSON estruturado

Cada lançamento também é distribuído com SLSA provenance (atestado por Sigstore) — garantia de que o pacote npm foi construído a partir do commit no repositório público.

Instalação

Claude Desktop (macOS)

Adiciona em ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_..."
      }
    }
  }
}

Reinicia o Claude Desktop. Na barra abaixo da caixa de chat aparecerá um ícone 🛠️ com o número de ferramentas carregadas.

Cursor

Adiciona em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Cline / Continue / Windsurf / Copilot / VS Code MCP

O mesmo comando npx @astroway/mcp funciona em qualquer cliente compatível com MCP. A configuração é idêntica — muda apenas o caminho para o ficheiro:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Cliente	Caminho para o ficheiro de configuração
Cline (VS Code)	.cline/mcp.json na raiz do workspace
Continue	~/.continue/config.json (sob mcpServers)
Windsurf	~/.codeium/windsurf/mcp_config.json
GitHub Copilot Chat (VS Code)	flag de preview → mcp.json no workspace
VS Code MCP extension	~/.vscode/mcp.json

Outros clientes MCP

Executa como servidor stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Dica

Obtém a tua chave em api.astroway.info/dashboard/sign-up. O plano gratuito inclui 10 000 créditos/mês, sem necessidade de cartão.

Privacidade — desde v1.0.0+

Este servidor MCP não envia nada de volta para a AstroWay além dos próprios pedidos de API que lhe pedes para executar. Sem telemetria, sem analytics, sem opção de opt-in/opt-out — silêncio por defeito.

Os pedidos de saída incluem dois headers de identificação para que o backend da AstroWay consiga distinguir o tráfego MCP dos pedidos HTTP diretos nos seus próprios logs:

• User-Agent: astroway-mcp/<version> (Node/<node-version>)
• X-Astroway-Channel: mcp

Nenhum deles contém session ID, fingerprint de máquina ou qualquer coisa pessoal. Trata-se da semântica padrão de User-Agent — cada ferramenta CLI envia informação semelhante.

Registo de subconjunto — desde v1.0.0+

Se usas apenas uma parte do catálogo — regista um subconjunto para manter a janela de contexto do LLM compacta:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // apenas estes prefixos
    "ASTROWAY_READONLY": "1"                               // ignora grupos ai/horoscope/reports (backed por LLM, gastam créditos)
  }
}

Grupos comuns: western, vedic, tarot, numerology, hd (Human Design), relational (sinastria/composta/Davison), prognostics (trânsitos/progressões/retornos), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Executa npx @astroway/mcp --list-tools para ver o conjunto completo.

ASTROWAY_READONLY=1 ignora os três grupos que internamente chamam LLM (ai, horoscope, reports) — útil quando queres apenas matemática determinística de cartas sem gastar créditos em geração de texto.

Compromisso de estabilidade — desde v1.0.0+

• Catálogo congelado durante a sessão. 624 ferramentas, 12 prompts, 14 recursos estão incluídos no pacote npm publicado no momento da compilação — nada muda durante a conexão. Se o teu cliente fizer cache de tools/list após a primeira chamada, ele permanece correto para toda a sessão.
• Identificadores de ferramentas estáveis dentro da mesma versão major. O nome sob astroway_<group>_<tool> não será renomeado ou removido dentro de v1.x sem uma nota de deprecation no CHANGELOG.md e disponibilidade paralela mínima de um minor.
• Forma de entrada da ferramenta estável dentro da mesma versão minor. Restrições (regex, intervalo, enum) chegam em patches; adição de um campo obrigatório requer um bump minor.
• Atualização do catálogo — reinstalando. npm i -g @astroway/mcp@latest (ou npx -y @astroway/mcp na tua configuração) atualiza o conjunto na próxima inicialização.

Exemplos de prompts

Após conectares o servidor, pede ao AI:

Carta natal

Calcula a minha carta natal — nascido a 15 de março de 1990, 14:30, em Kiev. Descreve o Sol, a Lua, o Ascendente e encontra aspetos apertados.

O Claude chamará a ferramenta chart com os teus parâmetros, receberá um JSON estruturado e descreverá a carta em palavras.

Trânsitos

Quais os trânsitos significativos dos planetas lentos que ocorrerão na minha carta natal durante o ano de 2027?

O Claude faz duas chamadas de ferramenta: primeiro transits (snapshot atual), depois transit-calendar (intervalo). Interpreta as tendências.

Mahadasha Vedanta

Executa a Vimshottari Mahadasha para uma pessoa nascida a 22.07.1985 06:45 em Mumbai. Em que período esta pessoa se encontra atualmente?

Através da ferramenta vedic/dashas/vimshottari/maha — timestamp UTC exato do período atual.

Sinastria

Compara duas cartas: A — 10.06.1988 09:15 Londres, B — 22.11.1991 22:40 Berlim. Quais os aspetos cruzados mais fortes?

Ferramenta synastry com dois blocos chart + interpretação da pontuação de compatibilidade.

Tarot

Tira 3 cartas Rider-Waite-Smith: Passado — Presente — Futuro. Pergunta: «devo aceitar o novo emprego?». Seed = 42.

tarot/rider-waite/spread com seed fixo para reprodutibilidade.

Lista de todas as ferramentas

Após conectares, pergunta ao Claude:

Lista todas as ferramentas AstroWay.

Ou pela linha de comando:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (executa o servidor stdio; as chamadas protocolares de tool-list são feitas pelo cliente MCP)

Configuração

Variável	Valor por defeito	Descrição	Desde a versão
ASTROWAY_API_KEY	(obrigatório)	Live: aw_live_.... Sandbox: aw_test_....	0.1.0
ASTROWAY_BASE_URL	https://api.astroway.info/v1	Override para ambientes self-hosted/staging.	0.1.0
ASTROWAY_TOOL_GROUPS	(todos os grupos)	Prefixos separados por vírgulas para limitar o catálogo (western,vedic,relational).	1.0.0
ASTROWAY_READONLY	0	1 ignora grupos backados por LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug — nível de logging para stderr.	0.8.0
LOG_FILE	(não gravado)	Caminho para ficheiro para duplicar logs.	0.8.0
MCP_FLAT_TOOLS	0	1 devolve nomes flat pré-v0.9 (chart em vez de astroway_western_chart). Legacy.	0.9.0

Porque MCP e não integração direta

Um LLM genérico (sem grounding) dirá «algures em julho Saturno formará um trígono com o teu Júpiter» — sem data exata, com uma margem de erro de ±15 dias. Um agente MCP faz tool_use POST /v1/transits e devolve um timestamp UTC até ao segundo, com base no Swiss Ephemeris real.

A vantagem não está no LLM, mas na garantia de que a matemática é real — não inventada.

Distribuição do pacote

• mcp.so listing: mcp.so/server/astroway-mcp/astroway
• mcpservers.org: aguarda aprovação (até maio de 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Ligações

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 Documentação da API: /docs/api/
• 🔑 Inscrição: /dashboard/sign-up
• 💰 Preços: /pricing/
• 🌐 Repositório público (MIT): github.com/astroway/astroway-mcp