# MCP — conexão Claude / Cursor O servidor Model Context Protocol (MCP) AstroWay expõe **todos os {siteMeta.endpoints} 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](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · hosted: [mcp.astroway.info/health](https://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](https://api.astroway.info/dashboard/sign-up) (10 000 créditos/mês grátis). Clica no botão — o Cursor abrirá, pedirá confirmação e adicionará automaticamente a entrada: Install in Cursor → :::caution[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](https://api.astroway.info/dashboard/keys). 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`). ::: 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. Para Cline / Continue / Windsurf ou versões antigas do Claude Desktop / Cursor: ```json { "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 ```bash 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`: ```json { "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](https://status.astroway.info). Incidentes com duração superior a 5 minutos são publicados como postmortem em até 5 dias úteis (conforme [/sla/](/sla/)). ## Stdio (npm) — para desenvolvimento local O pacote [`@astroway/mcp`](https://www.npmjs.com/package/@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](https://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/` 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](https://search.sigstore.dev/)) — 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`: ```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`: ```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: ```json { "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: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## 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/ (Node/)` - `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: ```jsonc { "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__` 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: ```bash 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](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** aguarda aprovação (até maio de 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Ligações - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 Documentação da API: [/docs/api/](/docs/api/) - 🔑 Inscrição: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Preços: [/pricing/](/pricing/) - 🌐 Repositório público (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)