RoxyAPI
Quick StartPlaygroundSDKMCP SetupFree TemplatesAGENTS.md
  1. Docs
  3. Build With Roxy
  5. Cursor

Cursor, connect Roxy as an MCP server and docs source

Register Roxy once, then build spiritual-data features in natural language with full endpoint knowledge. Time to ship: 5 minutes.

Cursor is the most popular AI code editor. Roxy works with Cursor through MCP servers and docs indexing. Add Roxy docs and the agent builds with real API knowledge instead of guessing. Add the per-domain MCP servers and the agent can call Roxy endpoints directly while you build.

What you can build with this

  • Natal chart, kundli, tarot, numerology, and dream features generated inline
  • Full apps scaffolded from single prompts ("build a tarot reader with the three-card spread")
  • Typed TypeScript code generated against live OpenAPI schemas
  • Project rules that keep Cursor on the right base URL, auth, and language conventions
  • MCP-driven prototyping 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. Cursor installed.

Step 1, add Roxy docs to Cursor

Give Cursor full knowledge of every Roxy endpoint, parameter, and response shape.

  1. In any Cursor chat, type @Docs then click Add new doc.
  2. Paste the URL https://roxyapi.com/api-reference.
  3. Name it RoxyAPI.
  4. Cursor crawls the Scalar-rendered API reference and indexes every endpoint.

Now @Docs RoxyAPI in any prompt gives Cursor full API context. Manage indexed docs later from Cursor Settings > Features > Docs.

Point @Docs at /api-reference (Scalar live docs) rather than /llms.txt. The Scalar page walks every tag and endpoint with full request/response schemas.

For tight execution context (without indexing the full Scalar reference), drop the site-level AGENTS.md URL into Cursor too: @Docs https://roxyapi.com/AGENTS.md. It is a tight 120-line execution playbook with Rule 0, common task body shapes, and the field gotcha table. Smaller context, faster recall.

The docs MCP server is the on-ramp for Cursor. It exposes one tool, search_docs, that 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.

Visit the MCP setup page or use the config below. Cursor supports either a project-scoped .cursor/mcp.json or a global ~/.cursor/mcp.json.

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

Save as .cursor/mcp.json in your project root. No key needed, the docs server is public.

Now just ask Cursor 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 3, add domain servers for live calls (optional)

The docs server teaches Cursor 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.

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

Save as .cursor/mcp.json in your project root. Export ROXY_API_KEY in your shell before launching Cursor.

If you inline the API key directly (instead of using ${env:ROXY_API_KEY}), add .cursor/mcp.json to .gitignore. A committed config with a real key is the single most common way API keys leak into public repos.

Step 4, verify the MCP server is connected

After saving .cursor/mcp.json:

  1. Open Cursor Settings > Features > MCP. Your roxy-docs server (plus any domain servers you added) should show a green "connected" status.
  2. Open the agent chat (Cmd+L / Ctrl+L) and ask "list the Roxy tools you have access to".
  3. The agent should enumerate the tools it discovered. The docs server exposes search_docs. Each domain server you added exposes its own tools (for example get_astrology_horoscope_sign_daily, post_astrology_natal_chart).
  4. Smoke test: "using roxy-docs, find the daily horoscope endpoint and show me how to call it".

Step 5, first prompt to try

Paste into Cursor chat or inline edit.

  • Using @Docs RoxyAPI, build a birth chart component that takes a date, time, and city.
  • Using roxy-docs, add a tarot daily card to my homepage.
  • Create a numerology calculator page with Life Path, Expression, and Soul Urge numbers. @Docs RoxyAPI
  • Build a dream symbol search with autocomplete using the dreams API. @Docs RoxyAPI
  • Using @Docs RoxyAPI, add a Vedic astrology kundli page with planet positions and dasha periods.

Add project rules

The current Cursor rules format is .mdc with YAML frontmatter. Create .cursor/rules/roxy.mdc so Cursor follows Roxy conventions in every prompt:

---
description: Roxy API conventions
alwaysApply: true
---

When using Roxy API:
- Base URL: https://roxyapi.com/api/v2
- Auth: X-API-Key header from env ROXY_API_KEY
- Never expose the API key in client-side code
- Typed SDK reference: https://roxyapi.com/docs/sdk (npm install @roxyapi/sdk for TypeScript, pip install roxy-sdk for Python, composer require roxyapi/sdk for PHP 8.2+)
- Reference docs: @Docs RoxyAPI
- Errors return { error, code } (no success wrappers)
- Multi-language: add ?lang=xx (tr, de, es, hi, pt, fr, ru)
- Always geocode via /location/search before chart endpoints
- Prefer IANA timezones (America/New_York) over decimal offsets

alwaysApply: true injects the rule into every chat. Use globs: ["**/*.ts", "**/*.tsx"] if you only want it active in specific file types.

Generate TypeScript types

Generate typed client code from any Roxy OpenAPI spec:

npx openapi-typescript https://roxyapi.com/api/v2/astrology/openapi.json -o src/api/astrology.ts

Available specs: astrology, vedic-astrology, numerology, tarot, human-design, forecast, biorhythm, iching, crystals, dreams, angel-numbers, location.

Or install the SDK for pre-built types across all domains in TypeScript, Python, PHP, or C#:

npm install @roxyapi/sdk          # TypeScript
pip install roxy-sdk               # Python
composer require roxyapi/sdk       # PHP 8.2+
dotnet add package RoxyApi.Sdk     # C#

Gotchas

  • ${env:VAR} only interpolates vars set before Cursor launched. Quit Cursor, export ROXY_API_KEY=..., then relaunch with cursor . from that terminal.
  • Invalid JSON silently fails. Paste .cursor/mcp.json into a JSON linter after editing. Reload the window (Cmd+Shift+P > Developer: Reload Window) to pick up changes.
  • 401 after config edit. Run echo $ROXY_API_KEY in the launching terminal, relaunch Cursor from there. Strip quotes and whitespace from the key.
  • @Docs and the per-domain MCP servers solve different problems. @Docs and the keyless roxy-docs server give the agent endpoint knowledge for writing code. The per-domain MCP servers let the agent actually call those endpoints during the session. Use both.
  • Never commit a real key. If you inline it instead of using env interpolation, gitignore the config.

What to build next

  • The MCP setup docs cover every other MCP client (Claude Code, Claude Desktop, Antigravity, OpenAI Agents, Gemini Agents).
  • The Claude Code guide uses the same MCP servers in the terminal.
  • The Antigravity guide uses them in the Google Gemini 3 Pro IDE.
  • The SDK docs cover typed calls in TypeScript, Python, PHP, and C#.
  • The AI chatbot tutorial builds a multi-domain chatbot on the same servers.