Replit, connect Roxy as an MCP server

Add Roxy to Replit Agent from the Integrations pane, then build spiritual-data features in natural language. Remote MCP, all in the browser. Time to ship: 5 minutes.

Replit Agent connects to MCP servers from the Integrations pane, so it can call real tools while it builds your app. RoxyAPI runs as a Remote MCP server over streamable HTTP, so Agent 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. Nothing to install locally, it all runs in the browser.

What you can build with this

• Natal chart components wired end-to-end ("build me a 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 Agent 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. A Replit account with Agent access. Sign up at replit.com.

Step 1, add the docs server (keyless)

The docs server is the on-ramp for Agent. It searches the entire Roxy reference so 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.

One-click install: open this Add-to-Replit link and confirm. Or add it by hand: in your Repl, open the Integrations pane, choose Add a custom MCP server, and paste the URL:

https://roxyapi.com/mcp/docs

Agent fetches the tool list automatically. Now just ask in plain language:

Use the RoxyAPI Docs server to integrate the 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 Agent how to build. To let it 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. Replit sends custom headers on every MCP request, so add the key as an X-API-Key header.

In the Integrations pane, choose Add a custom MCP server and enter:

• URL: https://roxyapi.com/mcp/astrology
• Custom header: name X-API-Key, value your key from your account

Repeat for any other domain you need: numerology, tarot, vedic-astrology, human-design, forecast, biorhythm, iching, crystals, dreams, angel-numbers, or location. Swap the last path segment for the domain and reuse the same X-API-Key header.

Step 3, building a deployed app

The MCP connection lets Agent call Roxy while you build and chat. For an app you deploy to real users, call the REST API from the server side with the key kept in Replit Secrets, never in the browser:

1. Open the Secrets pane and add ROXY_API_KEY with your key.
2. Have Agent read it from the environment and call Roxy from a backend route.

Add a backend route that reads ROXY_API_KEY from the environment and calls
https://roxyapi.com/api/v2/astrology/horoscope/{sign}/daily with the
X-API-Key header. The frontend calls my route, never roxyapi.com directly.

Step 4, first prompt to try

Ask Agent one of these. 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 page. Call the natal chart endpoint, inspect the response, and render planets, houses, and aspects.
• Add numerology compatibility to my app. Call the compatibility endpoint with two names and birth dates, then build the scoring UI.

Add Roxy context to your Agent prompt

Lead your build prompt with this block so Agent wires Roxy correctly instead of guessing:

## 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, server-side only (Replit Secret: ROXY_API_KEY)
- Multi-language: add ?lang=xx (supported: tr, de, es, hi, pt, fr, ru)
- For any chart endpoint, call the 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. Point Agent at the site-level AGENTS.md at https://roxyapi.com/AGENTS.md for the tight, language-agnostic execution playbook with Rule 0, common task body shapes, and the field gotcha table.

Gotchas

• Custom header for the key. Roxy per-domain servers authenticate with X-API-Key. Add it as a custom header on the server in the Integrations pane, not a bearer token.
• Keyless docs vs keyed domains. The docs server needs no key and returns documentation. Only the per-domain servers make live calls and take the X-API-Key header.
• Never ship the key to the browser. In a deployed app, keep ROXY_API_KEY in Replit Secrets and call Roxy from a backend route. The frontend calls your route, never roxyapi.com.
• Security scanner. Replit scans MCP traffic and can hold a tool for approval. Approve Roxy tools when prompted.
• Geocode first for chart endpoints. Natal chart, kundli, panchang, and synastry all need latitude, longitude, and timezone. Tell Agent to call the location search 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 Cursor guide use the same servers in other agents and editors.
• The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
• The API reference lets you explore endpoints before asking Agent to wire them up.