# MCP — connecting Claude / Cursor AstroWay's Model Context Protocol server exposes **all {siteMeta.endpoints} endpoints** as tools to an AI agent. Two modes — both supported natively by every MCP-compatible client. | Mode | URL / command | When to choose | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai in browser), Claude Desktop / Cursor / Code newcomers without npm, or when you want zero-install | | **Stdio (npm)** | `npx @astroway/mcp` | Cursor power users, local dev, privacy-conscious (key never leaves your machine), offline-ready | Hosted endpoint and npm package serve **the same tool catalogue** (generated from one `/v1/openapi.json`). Auth: same `aw_test_*` / `aw_live_*` API key — for hosted it's an `Authorization: Bearer …` header, for stdio it's the `ASTROWAY_API_KEY` env var. 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 Fast path without npm — pick your client. Before installing, grab a key at [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10,000 credits / month free). Click the button — Cursor opens, asks to confirm, adds the entry automatically: Install in Cursor → :::caution[Required step 2 — won't work otherwise] Cursor can't substitute secrets via deeplink — `~/.cursor/mcp.json` will get the literal `Bearer YOUR_API_KEY` string, which the server rejects with `403 invalid_format`. **After clicking the button:** 1. **Cursor Settings** (⚙️ top-right) → **Tools & MCP** → find `astroway-hosted` in the list. 2. Click the three-dot menu (`⋯`) next to the server → **Edit configuration**. 3. In the `Authorization` field, replace `Bearer YOUR_API_KEY` with `Bearer aw_test_…` (or `aw_live_…`) — your real key from the [Dashboard](https://api.astroway.info/dashboard/keys). 4. Save → reopen the MCP list → confirm status is **enabled** + green dot + `630 tools enabled` counter. Or edit the file directly: `~/.cursor/mcp.json` (`headers.Authorization`). ::: No JSON editing required. In any Claude Desktop chat: 1. Click **`+`** to the left of the input field → in the menu pick **"Add connector"**. 2. In the dialog, choose **"Add custom connector"**. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Expand **"Advanced settings"** → in **"Custom headers"** add: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (your key) 6. **Add** → find `astroway-hosted` in the Connectors list, toggle it on. **No restart needed.** Click `+` in a new chat — `astroway-hosted` appears under Connectors with all 630 tools + 12 prompts + 14 resources. For Cline / Continue / Windsurf or older versions of Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Config paths: - **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) or `.cursor/mcp.json` (workspace) - **Cline (VS Code):** `.cline/mcp.json` in workspace - **Continue:** `~/.continue/config.json` (under `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Fully restart the client after editing (Cmd+Q → reopen). ### Health check ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` In your client, ask: *"List 5 AstroWay tool names from astroway-hosted"*. You should see names like `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Rate limits The hosted endpoint sits behind a three-layer rate limit: Cloudflare's DDoS shield + nginx `120 req/min/IP` + in-memory bucket `60/60s/(IP+key)`. Real MCP clients (Claude Desktop, Cursor) don't come anywhere near these limits — they're not bursty. If your automation / CI needs > 120 req/min, use **stdio** mode instead (no limits at the hosted layer; goes straight to `api.astroway.info/v1/*` under your plan's tier rate limit). ### What if `mcp.astroway.info` is temporarily down If the hosted endpoint returns 5xx, your MCP client will surface an error on `tools/list`. This **does not affect** stdio clients — they spawn the local npm package and hit `api.astroway.info/v1/*` directly, no hosted intermediary. **Fallback for critical integrations:** add a **second MCP server** to your config in stdio mode — the client will auto-use it if the hosted server fails to respond to `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_..." } } } } ``` Real hosted-endpoint uptime is published at [status.astroway.info](https://status.astroway.info). Incidents lasting > 5 minutes get a public postmortem within 5 business days per [/sla/](/en/sla/). ## Stdio (npm) — for local development [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) is the npm package that runs locally as a subprocess. One npm package, native integration with Claude Desktop, Cursor, and any MCP-compatible client. ## How it works The tool list is generated **at build time** from the live OpenAPI spec ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Every package release picks up new endpoints automatically — no manual maintenance. Each endpoint becomes a tool: - `tools/list` returns a description and input schema (with a request body example) - `tools/call` POSTs to `https://api.astroway.info/v1/` using your `ASTROWAY_API_KEY` - The response is returned to the agent as structured JSON Each release also ships SLSA provenance ([Sigstore-attested](https://search.sigstore.dev/)) — a guarantee that the npm package was built from the exact commit in the public source repo. ## Install ### Claude Desktop (macOS) Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Restart Claude Desktop. A 🛠️ indicator with the loaded tool count appears under the chat input. ### Cursor Add to `~/.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 The same `npx @astroway/mcp` command works in every MCP-compatible client. Identical config — only the path to the config file differs: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Client | Config path | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` in workspace root | | **Continue** | `~/.continue/config.json` (under `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | enable preview → `mcp.json` in workspace | | **VS Code MCP extension** | `~/.vscode/mcp.json` | ### Other MCP clients Run as a stdio server: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Privacy — from v1.0.0+ This MCP server **does not phone home**. There is no telemetry, no analytics, no usage reporting — and no opt-in / opt-out toggle. The only network traffic the server originates is the AstroWay API calls you ask it to make, going directly from your machine to `https://api.astroway.info/v1`. Outgoing requests carry two identifying headers so the AstroWay backend can distinguish MCP traffic from raw HTTP traffic in its own logs: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Neither carries a session ID, machine fingerprint, or anything personal. They mirror standard `User-Agent` semantics — every CLI tool already sends similar information. ## Subset registration — from v1.0.0+ If you only use part of the catalogue, register a subset and keep your LLM context window lean: ```jsonc { "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) } } ``` Common groups: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastry/composite/davison), `prognostics` (transits/progressions/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Run `npx @astroway/mcp --list-tools` to inspect the full set. `ASTROWAY_READONLY=1` skips the three groups that internally call an LLM (`ai`, `horoscope`, `reports`) — useful when you want pure deterministic chart math without burning credits on text generation. ## Stability commitment — from v1.0.0+ - **Catalogue is frozen for the duration of a session.** The 624 tools, 12 prompts, and 14 resources are baked into the published npm package — they don't change at runtime. If your client caches `tools/list` after the first call, it stays correct for the whole connection. - **Tool identifiers are stable inside a major version.** A name shipped under `astroway__` won't be renamed or removed within `v1.x` without a deprecation note in `CHANGELOG.md` and a one-minor parallel-availability window. - **Tool input shape is stable inside a minor version.** Tightening (regex, range, enum) ships in patches; adding a required field requires a minor bump. - **Refresh the catalogue by reinstalling.** `npm i -g @astroway/mcp@latest` (or the `npx -y @astroway/mcp` form already in your client config) pulls the current set on the next start. ## Example prompts After connecting the server, ask the AI: ### Natal chart > Calculate my natal chart — born 1990-03-15 14:30 in Kyiv. Describe the Sun, Moon, Ascendant and find any tight aspects. Claude calls the `chart` tool with your params, gets structured JSON, and describes the chart in natural language. ### Transits > Which significant outer-planet transits hit my natal chart during 2027? Claude makes two tool calls: first `transits` (current snapshot), then `transit-calendar` (range). Interprets the trends. ### Vedic Mahadasha > Run Vimshottari Mahadasha for someone born 1985-07-22 06:45 in Mumbai. Which period are they in right now? Through the `vedic/dashas/vimshottari/maha` tool — exact UTC timestamp for the current period. ### Synastry > Compare two charts: A — 1988-06-10 09:15 London, B — 1991-11-22 22:40 Berlin. What are the strongest cross-aspects? `synastry` tool with two `chart` blocks + compatibility score interpretation. ### Tarot > Pull 3 Rider-Waite-Smith cards: Past — Present — Future. Question: "should I take the new job?". Seed = 42. `tarot/rider-waite/spread` with a fixed seed for reproducibility. ## Listing all tools After connecting, ask Claude: > List all astroway tools. Or from the command line: ```bash 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) ``` ## Configuration | Variable | Default | Description | Since | |---|---|---|---| | `ASTROWAY_API_KEY` | *(required)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Override for self-hosted / staging environments. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(all groups)* | Comma-separated prefixes to limit catalogue (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` skips LLM-backed groups (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — stderr log verbosity. | 0.8.0 | | `LOG_FILE` | *(not written)* | File path to mirror stderr logs to. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` returns pre-v0.9 flat names (`chart` instead of `astroway_western_chart`). Legacy. | 0.9.0 | ## Why MCP, not direct integration A generic LLM (without grounding) will say *"some time in July Saturn will trine your Jupiter"* — no exact date, ±15 days drift. **The MCP agent** does `tool_use POST /v1/transits` and returns a UTC timestamp **down to the second**, on real Swiss Ephemeris. The win isn't from the LLM — it's the **guarantee that the math is real**, not made up. ## Package distribution - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** awaiting approval (as of May 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Links - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 API docs: [/docs/api/](/docs/api/) - 🔑 Sign up: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Pricing: [/pricing/](/pricing/) - 🌐 Public repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)