Skip to content
RoxyAPI
Quick StartPlaygroundSDKMCP SetupFree TemplatesAGENTS.md
  1. Docs
  3. Build With RoxyAPI
  5. Cursor

Cursor astrology MCP, IDE setup and prompts

One JSON file gives Cursor the whole RoxyAPI reference as a searchable tool. Add your key and the agent runs live calculations while it writes the code. Five minutes, no local process.

Cursor connects to RoxyAPI over Remote MCP. The keyless docs server answers every question about endpoints, fields and SDK methods, so the agent stops inventing paths, and a per-domain server lets it pull a real natal chart, horoscope or tarot spread mid-build.

Step 1, the docs server (keyless)

Cursor reads MCP servers from mcp.json. Create .cursor/mcp.json in the project root, or ~/.cursor/mcp.json to have it everywhere:

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

That is one tool, search_docs, over the entire reference: endpoints, request and response fields, SDK methods, auth, integration steps. No API key, documentation only, never a live calculation.

Manage and toggle servers from Customize in the sidebar. Then ask in plain language:

Using roxy-docs, find the natal chart endpoint and show me how to call it with the TypeScript SDK.

Step 2, a domain server for live calls

Live calculations take your key in the X-API-Key header, one server per domain. Cursor resolves ${env:VAR} inside url and headers, so the key stays in your environment:

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

Export ROXY_API_KEY in your shell, then launch Cursor from that shell.

Get a key on the pricing page, or mint another at your account.

Step 3, point Cursor at the truth sources

Cursor reads AGENTS.md from the project root, so one file covers Cursor and every other agent on the repo. Add:

## RoxyAPI
- Search https://roxyapi.com/mcp/docs (tool: search_docs) before writing any RoxyAPI call. No MCP in this context? Fetch https://roxyapi.com/llms.txt instead.
- Read https://roxyapi.com/AGENTS.md in full before the first call: auth, the location rule, request body shapes, the error contract, the SDK for this language.
- Print request and response fields with jq from https://roxyapi.com/api/v2/{domain}/openapi.json before using an endpoint. Generate types from that spec, never by hand.
- Base URL https://roxyapi.com/api/v2. Auth is the X-API-Key header read from ROXY_API_KEY, server side only, never in client code.
- Every chart, horoscope, panchang, dasha and compatibility call needs latitude, longitude and timezone from GET /location/search?q={city}. Never ask a person for coordinates.
- A 200 is clean JSON with no wrapper. Errors are { error, code, doc_url }, and a 400 carries issues[]. Retry only 429 and 5xx.
- Add ?lang= for en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant.

Want it always on as a project rule instead? Save the same body as .cursor/rules/roxyapi.mdc with this frontmatter. A plain .md file in .cursor/rules is ignored, because the rules system reads the frontmatter:

---
description: RoxyAPI conventions
alwaysApply: true
---

Step 4, copy the prompt for what you are building

Every app prompt lives on one page: AI prompts. Adding a feature to a repo you already have is the Add RoxyAPI to an existing app prompt; a whole app from a blank project is Astrology Birth Chart App or the domain prompt beside it.

Frequently asked questions

Should I index the RoxyAPI reference as a doc source in Cursor?

No. The @ menu covers files and folders, terminals, chats, git diffs and the browser, and there is no documentation indexer to point at an API reference. The keyless docs MCP server does that job better: it searches the live reference and returns the endpoint, the fields and the SDK call, so nothing goes stale between crawls.

How do I keep the RoxyAPI key out of .cursor/mcp.json?

Write "X-API-Key": "${env:ROXY_API_KEY}" and export the variable in your shell. Cursor resolves interpolation in command, args, env, url and headers. It reads the environment Cursor was launched from, so quit Cursor, export the key, and relaunch with cursor . from that terminal. The envFile option does not apply here, it is stdio only.

Cursor is not picking up my edit to mcp.json. Why?

Invalid JSON fails silently, so lint the file after editing. Then reload the window with Developer: Reload Window from the command palette. Server status and the enable toggle both live under Customize in the sidebar, and MCP connection errors go to the Output panel under MCP Logs.

Why does the agent only see some of the RoxyAPI tools?

Every connected tool is a schema in the context window on every turn, so connecting all 18 domains crowds out the conversation. Connect the domains you are building on and disable the rest from Customize. The context ring beside the prompt input shows what the MCP catalog is costing you.

Is RoxyAPI free to try with Cursor?

The docs server at https://roxyapi.com/mcp/docs needs no key and returns documentation, so the agent writes correct code from the first prompt. Live calculations across the domains need a key from the pricing page, billed flat, 1 request to 1 quota unit, every domain included.