MCP - conexão Claude / Cursor

O servidor Model Context Protocol do AstroWay expõe todos os 771 endpoints como ferramentas para um agente 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	Claude Web (claude.ai no navegador), Claude Desktop / Cursor / Code newcomers sem npm, ou quando queres zero-install
Stdio (npm)	npx @astroway/mcp	Cursor power users, desenvolvimento local, privacy-conscious (a chave nunca sai da tua máquina), offline-ready

O endpoint hosted e o pacote npm usam o mesmo catálogo de ferramentas (gerado a partir de um único /v1/openapi.json). Autenticação: a mesma chave de API aw_test_* / aw_live_* – no hosted é enviada através do cabeçalho Authorization: Bearer …, no stdio – através da variável de ambiente ASTROWAY_API_KEY.

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

Hosted (mcp.astroway.info) - zero install

Início rápido sem npm – escolhe o teu cliente. Antes da instalação, obtém a chave em api.astroway.info/dashboard/sign-up (10 000 créditos/mês gratuitamente).

Cursor (one-click)

Clica no botão – o Cursor abrirá, pedirá confirmação, e adicionará o registo automaticamente:

Instalar no Cursor →

2º passo obrigatório - caso contrário, não funcionará

O Cursor não consegue inserir o segredo do deeplink – em ~/.cursor/mcp.json será gravado o literal Bearer YOUR_API_KEY, ao qual o servidor responde 403 invalid_format.

Após clicar no botão:

1. Cursor Settings (⚙️ canto superior direito) → Tools & MCP → encontra 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 do Dashboard.
4. Guarda → abre novamente a lista de MCP → certifica-te de que o status é enabled + ponto verde + contador 780+ tools enabled.

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

Nota

O Cursor impõe um limite no comprimento dos nomes: server_name:tool_name ≤ 60 caracteres. Cerca de 90 das 780+ ferramentas (principalmente os grupos hellenistic_*, psychological_*, zi_wei_*, zodiac_* e numerology_*) são filtradas pelo Cursor e não estarão disponíveis através do LLM. As restantes ~690 funcionam. No Claude Desktop não há tal limite – catálogo completo.

Claude Desktop

Settings → Developer → Edit Config abre claude_desktop_config.json. Este ficheiro executa apenas comandos locais: o registo com o url é ignorado com a mensagem “Some MCP servers couldn’t be loaded”. O servidor hosted é conectado através da ponte mcp-remote, que precisa de Node.js:

{
  "mcpServers": {
    "astroway-hosted": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.astroway.info/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer aw_live_..." }
    }
  }
}

Fecha completamente o Claude Desktop (Cmd+Q) e abre-o novamente. A chave está em env, porque o Claude Desktop no Windows quebra o argumento no espaço após Bearer.

O diálogo Add custom connector em Settings → Connectors aceita apenas o nome e o URL, não há campo para o cabeçalho Authorization, portanto, a chave AstroWay não pode ser transmitida através dele agora.

JSON config (manual)

Para Cursor, Cline, Continue e Windsurf, que aceitam um url remoto diretamente:

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

Caminhos para as configurações:

• Cursor: ~/.cursor/mcp.json (globalmente) 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 a edição, reinicia completamente o cliente (Cmd+Q → abrir novamente).

Verificação

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

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, …

Limites de taxa

O endpoint hosted é protegido por uma limitação de 3 níveis: camada Cloudflare DDoS + proxy de borda 120 req/min/IP + bucket em memória 60/60s/(IP+key). Clientes MCP reais (Claude Desktop, Cursor) não se aproximam desses limites – eles não fazem pedidos em rajada. Se a tua automação / CI precisar de > 120 req/min – usa o modo stdio (não há limites lá, vai diretamente através de api.astroway.info/v1/* com o teu limite de taxa tarifário).

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

Se o endpoint hosted retornar 5xx, o cliente MCP verá um erro em tools/list. Isso não afeta os clientes stdio – eles executam um pacote npm local que vai diretamente para api.astroway.info/v1/* sem uma camada hosted intermédia.

Fallback para integrações críticas: adiciona um segundo servidor MCP na configuração com o modo stdio – o cliente irá usá-lo automaticamente se o hosted não responder a 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 visto em status.astroway.info. Incidentes > 5 minutos são publicados como postmortem dentro de 5 dias úteis (por /sla/).

Stdio (npm) - para desenvolvimento local

@astroway/mcp – um pacote npm que é executado localmente como um subprocesso. Um 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 construção a partir da especificação OpenAPI live (api.astroway.info/v1/openapi.json). Cada lançamento do pacote apanha automaticamente todos os novos endpoints – não é preciso manter nada manualmente.

Cada endpoint torna-se uma ferramenta do tipo:

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

Cada lançamento também é enviado com SLSA provenance (Sigstore-attested) – é uma garantia de que o pacote npm foi construído exatamente a partir do commit no repositório público.

Instalação

Claude Desktop (macOS)

Adiciona a ~/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 do chat, aparecerá um indicador 🛠️ com o número de ferramentas carregadas.

Cursor

Adiciona a ~/.cursor/mcp.json:

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

Cline / Continue / Windsurf / Copilot / VS Code MCP

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

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

Cliente	Caminho para a 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)	preview-flag → mcp.json no workspace
VS Code MCP extension	~/.vscode/mcp.json

Outros clientes MCP

Executa como um servidor stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Dica

Para obter a chave – em api.astroway.info/dashboard/sign-up. Nível gratuito – 10 000 créditos/mês, sem cartão.

Privacidade - desde v1.0.0+

Este servidor MCP não envia nada de volta para o AstroWay exceto as próprias chamadas de API que tu lhe dás para executar. Nenhuma telemetria, nenhum analytics, nenhum interruptor de opt-in/opt-out – silêncio por padrão.

Os pedidos de saída transportam dois cabeçalhos de identificação para que o backend do AstroWay possa distinguir o tráfego MCP do HTTP direto nos seus próprios registos:

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

Nenhum deles contém ID de sessão, fingerprint da máquina ou qualquer coisa pessoal. Esta é a semântica padrão de User-Agent – cada ferramenta CLI envia informações semelhantes.

Registo de subconjuntos - desde v1.0.0+

Se usares apenas uma parte do catálogo – regista um subconjunto para que a janela de contexto do LLM permaneça compacta:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // only these prefixes
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, costs credits)
  }
}

Grupos comuns: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Executa npx @astroway/mcp --list-tools para ver o conjunto completo.

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

Compromisso de estabilidade - desde v1.0.0+

• O catálogo é congelado durante a sessão. 780+ ferramentas, 12 prompts, 14 recursos são incorporados no pacote npm publicado no momento da construção – nada muda durante a conexão. Se o teu cliente cachear tools/list após a primeira chamada – ele permanece correto para toda a sessão.
• Os identificadores de ferramenta são estáveis dentro da versão major. O nome sob astroway_<group>_<tool> não será renomeado ou removido dentro de v1.x sem uma nota de depreciação em CHANGELOG.md e disponibilidade paralela de uma versão minor.
• O formato de entrada da ferramenta é estável dentro da versão minor. Restrições (regex, range, enum) chegam em patches; a adição de um campo obrigatório requer um minor bump.
• Atualização do catálogo: por reinstalação. npm i -g @astroway/mcp@latest (ou o formato npx -y @astroway/mcp na tua configuração) obtém o conjunto atual no próximo arranque.

Exemplos de prompts

Após conectar o servidor, pede à IA:

Mapa Natal

Calcula o meu mapa natal - nascido a 15 de março de 1990, 14:30, Kiev. Descreve o Sol, a Lua, o Ascendente e encontra aspetos próximos.

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

Trânsitos

Quais trânsitos significativos de planetas lentos afetarão o meu mapa natal durante o ano de 2027?

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

Mahadasha Védica

Executa Vimshottari Mahadasha para uma pessoa nascida a 22.07.1985 06:45 em Mumbai. Em que período está esta pessoa agora?

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

Sinastria

Compara dois mapas: A - 10.06.1988 09:15 Londres, B - 22.11.1991 22:40 Berlim. Quais são 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 um seed fixo para reprodutibilidade.

Lista de todas as ferramentas

Após a conexão, pergunta ao Claude:

Lista todas as ferramentas astroway.

Ou da linha de comando:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (starts the stdio server; tool-list calls come from the MCP client over the protocol)

Configuração

Variável	Por padrão	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	Substituição 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 suportados por LLM (ai, horoscope, reports).	1.0.0
LOG_LEVEL	error	silent/error/warn/info/debug - nível de log para stderr.	0.8.0
LOG_FILE	(não é escrito)	Caminho para o ficheiro para duplicar os logs.	0.8.0
MCP_FLAT_TOOLS	0	1 retorna nomes flat pré-v0.9 (chart em vez de astroway_western_chart). Legado.	0.9.0

Porquê 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 um desvio de ±15 dias. Um agente MCP faz um tool_use POST /v1/transits e retorna um timestamp UTC ao segundo, no verdadeiro Swiss Ephemeris.

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 (a partir de maio de 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Links

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 API docs: /docs/api/
• 🔑 Sign up: /dashboard/sign-up
• 💰 Pricing: /pricing/
• 🌐 Public repo (MIT): github.com/astroway/astroway-mcp