Claude Code, connect Roxy as an MCP server

Register Roxy once, then ask Claude to build spiritual-data features in natural language. Time to ship: 5 minutes.

Claude Code is the Anthropic terminal-based agentic coding tool. Roxy has native MCP support, so you can register it once and all 130+ endpoints become callable tools inside Claude Code. No manual tool definitions, no glue code.

What you can build with this

• Natal chart components wired end-to-end ("build me a React birth chart page")
• Daily horoscope Next.js routes with the right endpoint and response shape
• Tarot reading apps with spread selection and card imagery
• Vedic kundli and Gun Milan features for matrimonial products
• Numerology calculators, dream-symbol lookups, I Ching casters
• Any multi-domain chatbot where the agent picks the right tool per question

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page.
2. Claude Code installed. See Anthropic docs.

Step 1, add Roxy as an MCP server

Pick a scope based on how you work.

claude mcp add-json --scope user roxy-astrology \
  '{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

{
  "mcpServers": {
    "roxy-astrology": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/astrology",
      "headers": { "X-API-Key": "${ROXY_API_KEY}" }
    }
  }
}

cd my-project
claude mcp add --transport http roxy-astrology https://roxyapi.com/mcp/astrology --header "X-API-Key: YOUR_KEY"

# Paste your key once, then run the loop. Exporting first keeps the key
# out of each `claude mcp add-json` line in your shell history.
export ROXY_API_KEY="your-key-from-roxyapi.com/pricing"

for p in astrology vedic-astrology tarot numerology iching dreams crystals angel-numbers biorhythm location; do
  claude mcp add-json --scope user "roxy-$p" \
    "{\"type\":\"http\",\"url\":\"https://roxyapi.com/mcp/$p\",\"headers\":{\"X-API-Key\":\"$ROXY_API_KEY\"}}"
done

Step 2, verify the connection

Check the registration:

claude mcp list

You should see roxy-astrology (plus any other domains). Then start Claude Code:

claude

Run /mcp inside the session to open the MCP status panel. Every server should show as connected with its tool count.

Out-of-band smoke test:

curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: YOUR_KEY"

If that prints JSON, the key is fine. If it returns 401, re-check at your account.

Step 3, first prompt to try

Inside the Claude session, try one of these natural-language requests. Claude picks the right tool and wires it into real code.

• Draw me a tarot card.
• What is the daily horoscope for Aries?
• Look up dream symbols related to water.
• Calculate the Life Path number for someone born 1990-05-12.
• Build me a birth chart component for React using Roxy. Call the natal chart endpoint, inspect the response, and generate a typed component with planets, houses, and aspects.
• Add daily horoscope to my Next.js app: create a server action that fetches the endpoint, a UI component, and wire up the route.
• Add numerology compatibility to my dating app. Call the compatibility endpoint with two names and birth dates, then build the scoring UI.

Add Roxy context to CLAUDE.md

Drop this into your project CLAUDE.md so Claude understands conventions without re-reading docs every prompt:

## Roxy API
- Endpoint reference: https://roxyapi.com/llms.txt
- Base URL: https://roxyapi.com/api/v2
- Auth: X-API-Key header (env: ROXY_API_KEY)
- MCP server: already configured, tools auto-discovered
- Multi-language: add ?lang=xx (supported: tr, de, es, hi, pt, fr, ru)
- For any chart endpoint, call roxy-location search first to geocode the city.
- Prefer IANA timezone strings (America/New_York) over decimal offsets.

All three SDKs ship AGENTS.md bundled. For TypeScript projects, pull it into context with the @path import:

@node_modules/@roxyapi/sdk/AGENTS.md

For Python projects, install roxy-sdk from PyPI and point Claude at the bundled AGENTS.md inside the installed package (path depends on your venv). For PHP / Laravel / Symfony projects, install roxyapi/sdk from Packagist and import @vendor/roxyapi/sdk/AGENTS.md.

Or fetch the site-level AGENTS.md directly inside Claude Code with @https://roxyapi.com/AGENTS.md if no SDK is installed (raw HTTP, Go, Ruby, Rust projects).

Claude Code then understands every endpoint, parameter, and response shape on every prompt.

Gotchas

• Scope matters. If claude mcp list does not show your server, you probably ran claude mcp add with the default local scope from a different directory. Re-run with --scope user.
• /mcp panel shows failed. Test the URL with curl https://roxyapi.com/mcp/astrology -H "X-API-Key: YOUR_KEY". A 405 confirms the URL is reachable (MCP endpoint is POST-only). 401 means the key is wrong. A connection error means the URL is wrong.
• Project config does not pick up the key. For .mcp.json with ${ROXY_API_KEY}, the variable must be exported in the shell that launched Claude Code. echo $ROXY_API_KEY in the same terminal first.
• Claude ignores the tools. Add one line to CLAUDE.md: "When the user asks about astrology, tarot, numerology, dreams, or any spiritual topic, prefer the Roxy MCP tools over generating answers from training data."
• Geocode first for chart endpoints. Natal chart, kundli, panchang, synastry all need latitude, longitude, timezone. Tell Claude to call roxy-location first.

What to build next

• The MCP setup docs cover every other MCP client (Cursor, Claude Desktop, Antigravity, OpenAI Agents, Gemini Agents).
• The Cursor guide uses the same servers in the Cursor editor.
• The Antigravity guide uses them in the Google Gemini 3 Pro IDE.
• The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
• The API reference has a pre-filled test key. Use it to explore endpoints before asking Claude to wire them up.