# 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](https://docs.claude.com/en/docs/claude-code/overview) 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](/pricing).
2. Claude Code installed. See [Anthropic docs](https://docs.claude.com/en/docs/claude-code/overview).

## Step 1, add Roxy as an MCP server

Pick a scope based on how you work.


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

Registers across every project on your machine. Ideal for a solo developer.

### Project scope
Create `.mcp.json` at your project root, commit it, and have teammates export `ROXY_API_KEY` in their shell:

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

Env interpolation means the key is never committed.

### Local scope (one project only)
```bash
cd my-project
claude mcp add --transport http roxy-astrology https://roxyapi.com/mcp/astrology --header "X-API-Key: YOUR_KEY"
```

Stored in `~/.claude.json`, tied to this directory. Server vanishes when you change dirs.

### Add all 10 products
```bash
# 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
```

All ten Roxy MCP servers register at once. Run `claude mcp list` to confirm.

**Warning: Pasting `YOUR_KEY` directly into the CLI puts it in your shell history. Either `export ROXY_API_KEY=...` first and reference `$ROXY_API_KEY`, or use the project-scoped `.mcp.json` pattern where the key reads from `${ROXY_API_KEY}` at runtime.**

## Step 2, verify the connection

Check the registration:

```bash
claude mcp list
```

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

```bash
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:

```bash
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](/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:

```markdown
## 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](/docs/sdk "RoxyAPI TypeScript, Python, and PHP SDKs") ship `AGENTS.md` bundled. For TypeScript projects, pull it into context with the `@path` import:

```markdown
@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 <a href="/AGENTS.md" target="_blank" rel="noopener" title="AGENTS.md execution playbook for AI coding agents - tight 120-line guide language-agnostic">AGENTS.md</a> 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](/docs/mcp) cover every other MCP client (Cursor, Claude Desktop, Antigravity, OpenAI Agents, Gemini Agents).
- The [Cursor guide](/docs/guides/cursor) uses the same servers in the Cursor editor.
- The [Antigravity guide](/docs/guides/antigravity) uses them in the Google Gemini 3 Pro IDE.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) builds a multi-domain chatbot on top of these servers.
- The [API reference](/api-reference) has a pre-filled test key. Use it to explore endpoints before asking Claude to wire them up.