# MCP — conexión Claude / Cursor El servidor del protocolo Model Context Protocol (MCP) de **AstroWay** expone **todos los {siteMeta.endpoints} endpoints** como herramientas para agentes de IA. Hay dos modos, ambos compatibles de forma nativa con todos los clientes MCP. | Modo | URL / comando | Cuándo elegirlo | |---|---|---| | **HTTP alojado** | `https://mcp.astroway.info/mcp` | Principiantes en Claude Web (claude.ai en el navegador), Claude Desktop / Cursor / Code sin npm, o si quieres instalación cero | | **Stdio (npm)** | `npx @astroway/mcp` | Usuarios avanzados de Cursor, desarrollo local, preocupados por la privacidad (la clave nunca abandona tu máquina), listo para funcionar sin conexión | El endpoint alojado y el paquete npm usan **el mismo catálogo de herramientas** (generado a partir del mismo `/v1/openapi.json`). Autenticación: la misma clave `aw_test_*` / `aw_live_*` — en el modo alojado se envía mediante el `Authorization: Bearer …` header, mientras que en el modo stdio se usa la variable de entorno `ASTROWAY_API_KEY`. Fuente: [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · alojado: [mcp.astroway.info/health](https://mcp.astroway.info/health) ## Hosted (`mcp.astroway.info`) — instalación cero Empieza rápido sin npm: elige tu cliente. Antes de instalar, obtén tu clave en [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 créditos/mes gratis). Haz clic en el botón: Cursor se abrirá, pedirá confirmación y añadirá la entrada automáticamente: Instalar en Cursor → :::caution[Paso 2 obligatorio, de lo contrario no funcionará] Cursor no puede sustituir el secreto en el deeplink: en `~/.cursor/mcp.json` se escribirá el literal `Bearer YOUR_API_KEY`, al que el servidor responde con `403 invalid_format`. **Tras hacer clic en el botón:** 1. **Cursor Settings** (⚙️ esquina superior derecha) → **Tools & MCP** → busca `astroway-hosted` en la lista. 2. Haz clic en los tres puntos (`⋯`) junto al servidor → **Edit configuration**. 3. En el campo `Authorization`, reemplaza `Bearer YOUR_API_KEY` por `Bearer aw_test_…` (o `aw_live_…`) — tu clave real de [Dashboard](https://api.astroway.info/dashboard/keys). 4. Guarda → abre de nuevo la lista de MCP → verifica que el estado sea **enabled** + punto verde + contador `630 tools enabled`. Alternativamente, edita el archivo directamente: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Sin editar JSON. En cualquier chat de Claude Desktop: 1. Haz clic en el **`+`** a la izquierda del campo de entrada → en el menú selecciona **"Add connector"**. 2. En el diálogo, elige **"Add custom connector"**. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Expande **"Advanced settings"** → en **"Custom headers"** añade: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (tu clave) 6. **Add** → busca `astroway-hosted` en la lista de Connectors, activa el interruptor. No es necesario reiniciar Claude Desktop. Haz clic en `+` en un nuevo chat — en Connectors aparecerá `astroway-hosted` con todas las 630 herramientas + 12 prompts + 14 recursos. Para Cline / Continue / Windsurf o versiones antiguas de Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Rutas de los archivos de configuración: - **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) o `.cursor/mcp.json` (en el workspace) - **Cline (VS Code):** `.cline/mcp.json` en el workspace - **Continue:** `~/.continue/config.json` (bloque `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Tras editar, reinicia completamente el cliente (Cmd+Q → abrir de nuevo). ### Verificación ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` En el cliente, pide: *"List 5 AstroWay tool names from astroway-hosted"*. Debería devolver nombres como `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Límites de tasa El endpoint alojado está protegido por un límite de tres niveles: Cloudflare (capa DDoS) + nginx `120 req/min/IP` + bucket en memoria `60/60s/(IP+key)`. Los clientes MCP reales (Claude Desktop, Cursor) no se acercan a estos límites: no hacen ráfagas de solicitudes. Si tu automatización / CI necesita > 120 req/min, usa el modo **stdio** (allí no hay límites, se comunica directamente con `api.astroway.info/v1/*` con tu límite de tasa del plan). ### ¿Qué pasa si `mcp.astroway.info` está temporalmente inactivo? Si el endpoint alojado devuelve 5xx, el cliente MCP verá un error al llamar a `tools/list`. **Esto no afecta** a los clientes en modo stdio: ejecutan el paquete npm local, que se comunica directamente con `api.astroway.info/v1/*` sin pasar por la capa alojada intermedia. **Fallback para integraciones críticas:** añade un **segundo servidor MCP** en la configuración en modo stdio: el cliente lo usará automáticamente si el alojado no responde a `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_..." } } } } ``` El uptime real del endpoint alojado se puede consultar en [status.astroway.info](https://status.astroway.info). Los incidentes > 5 minutos se publican como postmortem en un plazo de 5 días hábiles (según [/sla/](/sla/)). ## Stdio (npm) — para desarrollo local [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) es un paquete npm que se ejecuta localmente como un subprocess. Un solo paquete npm, integración nativa con Claude Desktop, Cursor y cualquier cliente MCP. ## Cómo funciona La lista de herramientas se genera **en el momento de la compilación** a partir de la especificación OpenAPI en vivo ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Cada versión del paquete incluye automáticamente todos los nuevos endpoints: no hay que mantener nada manualmente. Cada endpoint se convierte en una herramienta con el siguiente comportamiento: - `tools/list` devuelve la descripción y el esquema de entrada (con un ejemplo del cuerpo de la solicitud) - `tools/call` realiza una solicitud HTTP POST a `https://api.astroway.info/v1/` con tu `ASTROWAY_API_KEY` - La respuesta se devuelve al agente como JSON estructurado Cada versión también se distribuye con la procedencia SLSA ([atestada por Sigstore](https://search.sigstore.dev/)): garantía de que el paquete npm se construyó exactamente a partir del commit en el repositorio público. ## Instalación ### Claude Desktop (macOS) Añade en `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Reinicia Claude Desktop. En la barra bajo el chat aparecerá el icono 🛠️ con el número de herramientas cargadas. ### Cursor Añade en `~/.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 El mismo comando `npx @astroway/mcp` funciona en cualquier cliente MCP. La configuración es idéntica: solo cambia la ruta del archivo: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Cliente | Ruta del archivo de configuración | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` en la raíz del workspace | | **Continue** | `~/.continue/config.json` (bajo `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | bandera de vista previa → `mcp.json` en el workspace | | **Extensión MCP de VS Code** | `~/.vscode/mcp.json` | ### Otros clientes MCP Ejecútalo como servidor stdio: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Privacidad — desde v1.0.0+ Este servidor MCP **no envía nada de vuelta a AstroWay** excepto las propias llamadas a la API que le pides ejecutar. Sin telemetría, sin analytics, sin interruptores de opt-in/opt-out: silencio por defecto. Las solicitudes salientes incluyen dos encabezados de identificación para que el backend de AstroWay pueda distinguir el tráfico MCP del HTTP directo en sus propios logs: - `User-Agent: astroway-mcp/ (Node/)` - `X-AstroWay-Channel: mcp` Ninguno de ellos contiene session ID, huella de máquina ni nada personal. Es la semántica estándar de `User-Agent`: cada herramienta CLI envía información similar. ## Registro de subconjuntos — desde v1.0.0+ Si solo usas una parte del catálogo, registra un subconjunto para mantener compacta la ventana de contexto del LLM: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // solo estos prefijos "ASTROWAY_READONLY": "1" // omitir ai/horoscope/reports (respaldados por LLM, consumen créditos) } } ``` Grupos comunes: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (sinastría/compuesto/Davison), `prognostics` (tránsitos/progresiones/retornos), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Ejecuta `npx @astroway/mcp --list-tools` para ver el conjunto completo. `ASTROWAY_READONLY=1` omite los tres grupos que internamente invocan LLM (`ai`, `horoscope`, `reports`) — útil si quieres matemáticas puras de cartas sin gastar créditos en generación de texto. ## Compromiso de estabilidad — desde v1.0.0+ - **Catálogo congelado durante la sesión.** 624 herramientas, 12 prompts y 14 recursos están integrados en el paquete npm publicado en el momento de la compilación: nada cambia durante la conexión. Si tu cliente almacena en caché `tools/list` tras la primera llamada, seguirá siendo correcto para toda la sesión. - **Identificadores de herramientas estables dentro de la misma versión principal.** El nombre bajo `astroway__` no será renombrado ni eliminado dentro de `v1.x` sin una nota de deprecación en `CHANGELOG.md` y disponibilidad paralela en minor durante al menos una versión. - **Forma de entrada de herramientas estable dentro de la misma versión menor.** Cambios en restricciones (regex, rangos, enum) llegan en parches; añadir un campo obligatorio requiere un bump de minor. - **Actualizar el catálogo reinstalando.** `npm i -g @astroway/mcp@latest` (o la forma `npx -y @astroway/mcp` en tu configuración) actualiza el conjunto actual en el próximo inicio. ## Ejemplos de prompts Tras conectar el servidor, pide al IA: ### Carta natal > Calcula mi carta natal — nacido el 15 de marzo de 1990, 14:30, Kiev. Describe el Sol, la Luna, el Ascendente y encuentra aspectos ajustados. Claude llamará a la herramienta `chart` con tus parámetros, obtendrá un JSON estructurado y describirá la carta con palabras. ### Tránsitos > ¿Qué tránsitos significativos de planetas lentos ocurrirán en mi carta natal durante 2027? Claude realiza dos llamadas a herramientas: primero `transits` (instantánea actual), luego `transit-calendar` (rango). Interpreta las tendencias. ### Mahadasha védico > Ejecuta Vimshottari Mahadasha para una persona nacida el 22/07/1985 a las 06:45 en Mumbai. ¿En qué período está actualmente? Mediante la herramienta `vedic/dashas/vimshottari/maha` — timestamp UTC exacto del período actual. ### Sinastría > Compara dos cartas: A — 10/06/1988 09:15 Londres, B — 22/11/1991 22:40 Berlín. ¿Cuáles son los aspectos cruzados más fuertes? Herramienta `synastry` con dos bloques `chart` + interpretación del puntaje de compatibilidad. ### Tarot > Extrae 3 cartas Rider-Waite-Smith: Pasado — Presente — Futuro. Pregunta: «¿debería aceptar el nuevo trabajo?». Seed = 42. `tarot/rider-waite/spread` con seed fijo para reproducibilidad. ## Lista de todas las herramientas Tras conectar, pide a Claude: > Enumera todas las herramientas de AstroWay. O desde la línea de comandos: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (inicia el servidor stdio; las llamadas protocolarias a tool-list las realiza el cliente MCP) ``` ## Configuración | Variable | Valor por defecto | Descripción | Desde versión | |---|---|---|---| | `ASTROWAY_API_KEY` | *(obligatorio)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Sobrescribe para entornos autoalojados/staging. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(todos los grupos)* | Prefijos separados por comas para limitar el catálogo (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` omite los grupos respaldados por LLM (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — nivel de logging en stderr. | 0.8.0 | | `LOG_FILE` | *(no se escribe)* | Ruta al archivo para duplicar logs. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` devuelve nombres planos pre-v0.9 (`chart` en lugar de `astroway_western_chart`). Legacy. | 0.9.0 | ## ¿Por qué MCP y no integración directa? Un LLM genérico (sin grounding) dirá *«en algún momento de julio Saturno formará un trígono con tu Júpiter»* — sin fecha exacta, con un margen de ±15 días. **El agente MCP** realiza `tool_use POST /v1/transits` y devuelve un timestamp UTC **hasta el segundo**, usando el auténtico Swiss Ephemeris. La ventaja no está en el LLM, sino en la **garantía de que la matemática es real** — no inventada. ## Distribución del paquete - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** en espera de aprobación (a mayo de 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Enlaces - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 Docs de la API: [/docs/api/](/docs/api/) - 🔑 Registro: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Precios: [/pricing/](/pricing/) - 🌐 Repositorio público (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)