RoxyAPI
Quick StartAGENTS.mdSDKMCP SetupFree StartersAPI Playground
  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 MCP server and the agent can call Roxy endpoints directly.

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.

Step 2, add Roxy as an MCP server

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-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 3, verify the MCP server is connected

After saving .cursor/mcp.json:

  1. Open Cursor Settings > Features > MCP. Your roxy-* servers 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 tools it discovered (for example get_astrology_horoscope_sign_daily, post_astrology_natal_chart).
  4. Smoke test: "use the Roxy MCP to get the horoscope for Aries today".

Step 4, 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.
  • Add a tarot daily card to my homepage using Roxy MCP.
  • 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, tarot, numerology, iching, dreams, crystals, angel-numbers, biorhythm, location.

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

npm install @roxyapi/sdk        # TypeScript
pip install roxy-sdk             # Python
composer require roxyapi/sdk     # PHP 8.2+

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 MCP solve different problems. Docs gives the agent endpoint knowledge for writing code. MCP lets 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, and PHP.
  • The AI chatbot tutorial builds a multi-domain chatbot on the same servers.