MCP — connecting Claude / Cursor

AstroWay’s Model Context Protocol server exposes all 723 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 · npm: npmjs.com/package/@astroway/mcp · hosted: 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 (10,000 credits / month free).

Click the button — Cursor opens, asks to confirm, adds the entry automatically:

Install in Cursor →

No JSON editing required. In any Claude Desktop chat:

Click + to the left of the input field → in the menu pick “Add connector”.
In the dialog, choose “Add custom connector”.
Name: astroway-hosted
URL: https://mcp.astroway.info/mcp
Expand “Advanced settings” → in “Custom headers” add:
- Key: Authorization
- Value: Bearer aw_live_... (your key)
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:

{
  "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

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:

{
  "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. Incidents lasting > 5 minutes get a public postmortem within 5 business days per /sla/.

Stdio (npm) — for local development

@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). 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/<path> using your ASTROWAY_API_KEY
The response is returned to the agent as structured JSON

Each release also ships SLSA provenance (Sigstore-attested) — 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:

{
  "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:

{
  "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:

{
  "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:

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/<version> (Node/<node-version>)
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:

{
  "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_<group>_<tool> 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:

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
mcpservers.org: awaiting approval (as of May 2026)
awesome-mcp-servers (punkpeye): PR #5972