Windsurf, connect Roxy as an MCP server

Add Roxy to Cascade in one JSON block, then build spiritual-data features in natural language. Remote MCP, no local server to run. Time to ship: 5 minutes.

Windsurf is the agentic AI editor now part of Devin Desktop, and its Cascade agent connects natively to MCP servers. RoxyAPI runs as a Remote MCP server over streamable HTTP, so Cascade 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 Cascade picks the right tool per question, a transit, a tarot pull, or a nakshatra, across the domains you connect under one key

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page.
2. Windsurf installed. Download it from windsurf.com.

Step 1, add the docs server (keyless)

The docs server is the on-ramp for Cascade. 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.

Windsurf stores MCP servers in ~/.codeium/windsurf/mcp_config.json. Open it from the MCPs icon in the top right of the Cascade panel, or from Devin Settings then Cascade then MCP Servers, and add the docs server:

{
  "mcpServers": {
    "roxy-docs": {
      "serverUrl": "https://roxyapi.com/mcp/docs"
    }
  }
}

Save and restart Windsurf so Cascade picks up the change. 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 Cascade 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. Remote HTTP servers use the serverUrl field, and these make live calls, so they take your API key in the X-API-Key header. Windsurf resolves ${env:VAR} inside headers, so the key stays in your environment, not the config file.

Export your key, then add the server to mcp_config.json:

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

{
  "mcpServers": {
    "roxy-docs": {
      "serverUrl": "https://roxyapi.com/mcp/docs"
    },
    "roxy-astrology": {
      "serverUrl": "https://roxyapi.com/mcp/astrology",
      "headers": { "X-API-Key": "${env:ROXY_API_KEY}" }
    }
  }
}

Add another block for any other domain you need: numerology, tarot, vedic-astrology, human-design, forecast, biorhythm, iching, crystals, dreams, angel-numbers, or location. Restart Windsurf after every change.

Step 3, verify the connection

Open the MCPs icon in the Cascade panel. Each configured server should appear with a green status and its tool count. If a server shows an error, restart Windsurf so it re-reads mcp_config.json.

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 Cascade, 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 Windsurf rules

Cascade reads workspace rules from .windsurf/rules/. Create .windsurf/rules/roxyapi.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. Point a rule 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. Cascade then understands every endpoint, parameter, and response shape on every prompt.

Gotchas

• serverUrl, not url. Windsurf remote HTTP servers use the serverUrl field. The mcp_config.json file is JSON with an mcpServers object, the same shape as Claude Desktop.
• 100-tool cap. Cascade limits itself to 100 tools total. Connect only the domains you need and disable unused tools on each server settings page.
• Restart after edits. Windsurf reads mcp_config.json at startup. Restart the editor after any config change.
• Export the key first. ${env:ROXY_API_KEY} reads from the shell environment. Confirm with echo $ROXY_API_KEY in the terminal that launched Windsurf.
• X-API-Key, not Authorization Bearer. Roxy uses a custom header. Put your key under headers as X-API-Key.
• Geocode first for chart endpoints. Natal chart, kundli, panchang, and synastry all need latitude, longitude, and timezone. Tell Cascade 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 Cursor guide and Codex guide use the same servers in other editors and agents.
• The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
• The API reference lets you explore endpoints before asking Cascade to wire them up.