Gemini CLI, connect Roxy as an MCP server

Register Roxy once with the gemini mcp command, then build spiritual-data features in natural language. Remote MCP, no local server to run. Time to ship: 5 minutes.

Gemini CLI is Google's open-source terminal AI agent. It connects to MCP servers through your settings.json, so it can call real tools while it writes code. RoxyAPI runs as a Remote MCP server over streamable HTTP, so Gemini reads the entire Roxy reference and writes correct integration code with the right endpoints and field names the first try. Start with the keyless docs server, then add a per-domain server (for example /mcp/tarot) to make live calls while you build. No local process, 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 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 Life Path calculators, dream-symbol lookups, I Ching hexagram casters
• Any multi-domain companion where Gemini picks the right tool per question, a transit, a tarot pull, or a nakshatra, across all 12 domains under one key

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page.
2. Gemini CLI installed. Follow the Gemini CLI setup.

Step 1, add the docs server (keyless)

The docs server is the on-ramp for Gemini. It searches the entire Roxy reference so the agent writes correct integration code with the right endpoints and field names the first try. No API key needed, it returns documentation, never live calls.

The gemini mcp add command writes to your settings.json. Register the docs server at user scope so it works in every project:

gemini mcp add --transport http --scope user roxy-docs https://roxyapi.com/mcp/docs

Start Gemini and run /mcp to confirm the server is connected. Now just ask in plain language:

using roxy-docs, integrate the RoxyAPI insight endpoints into my project

It reads the reference and wires up the endpoints, SDK calls, and types for you. No glue code, no guessing.

Step 2, add domain servers for live calls (optional)

The docs server teaches Gemini how to build. To let the agent run real readings while you build, like a live tarot draw or a real natal chart, add the per-domain servers. These make live calls, so they take your API key in the X-API-Key header.

gemini mcp add --transport http --scope user roxy-astrology \
  https://roxyapi.com/mcp/astrology --header "X-API-Key: YOUR_KEY"

{
  "mcpServers": {
    "roxy-docs": {
      "httpUrl": "https://roxyapi.com/mcp/docs"
    },
    "roxy-astrology": {
      "httpUrl": "https://roxyapi.com/mcp/astrology",
      "headers": { "X-API-Key": "YOUR_KEY" }
    }
  }
}

export ROXY_API_KEY="your-key-from-roxyapi.com/pricing"

for p in astrology vedic-astrology numerology tarot human-design forecast biorhythm iching crystals dreams angel-numbers location; do
  gemini mcp add --transport http --scope user "roxy-$p" \
    "https://roxyapi.com/mcp/$p" --header "X-API-Key: $ROXY_API_KEY"
done

Step 3, verify the connection

List the configured servers:

gemini mcp list

You should see roxy-docs plus any domain servers you added, each marked Connected. Inside a Gemini session, run /mcp to see every server with its tool count.

Out-of-band smoke test:

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

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

Step 4, first prompt to try

Inside Gemini, try one of these natural-language requests. It 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. Call the natal chart endpoint, inspect the response, and generate a typed component with planets, houses, and aspects.
• 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 GEMINI.md

Gemini reads GEMINI.md from your project (and ~/.gemini/GEMINI.md globally) as standing instructions on every prompt. Drop this block into GEMINI.md so it understands Roxy conventions without re-reading docs every prompt:

## Roxy API
- Integration playbook: https://roxyapi.com/AGENTS.md
- Endpoint reference: https://roxyapi.com/llms.txt
- OpenAPI spec: https://roxyapi.com/api/v2/openapi.json
- 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 five SDKs ship an AGENTS.md playbook bundled. To have Gemini read that file directly, add its name to the context file list in settings.json:

{
  "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }
}

Then point Gemini at the site-level AGENTS.md at https://roxyapi.com/AGENTS.md, the tight, language-agnostic execution playbook with Rule 0, common task body shapes, and the field gotcha table. Gemini then understands every endpoint, parameter, and response shape on every prompt.

Gotchas

• httpUrl, not url. In settings.json, streamable HTTP servers use httpUrl. The url field is for SSE, and command is for local stdio.
• Keys land in settings.json. Gemini CLI does not interpolate environment variables inside headers, so the key is stored in plaintext. Keep settings.json out of git and prefer user scope.
• X-API-Key, not Authorization Bearer. Roxy uses a custom header. Pass --header "X-API-Key: YOUR_KEY" or set it under headers.
• Use /mcp to check status. Inside a session, /mcp lists every server, its connection state, and its tools. gemini mcp list does the same from the shell.
• Geocode first for chart endpoints. Natal chart, kundli, panchang, and synastry all need latitude, longitude, and timezone. Tell Gemini to call roxy-location first.

Frequently asked questions

What to build next

• The MCP setup docs cover every other MCP client (Cursor, Claude Code, Codex, OpenAI Agents, Gemini Agents).
• The Codex guide and Claude Code guide use the same servers in other terminal agents.
• The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
• The API reference lets you explore endpoints before asking Gemini to wire them up.