Skip to content
RoxyAPI
Get API Key
Set up your AI agentGet startedAPI ReferenceSDKRemote MCPFree Templates

Cursor astrology MCP setup

One install gives Cursor the whole RoxyAPI reference as a searchable tool, plus a skill that knows every domain. 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)

The RoxyAPI plugin is the whole setup. It connects the keyless docs server and loads a skill that tells the agent when and how to build on every RoxyAPI domain. Clone it into the local plugins folder, then run Developer: Reload Window:

bash
git clone https://github.com/RoxyAPI/agent-plugin ~/.cursor/plugins/local/roxyapi

The plugin is a standard Agent Plugins package, the same one Claude Code installs, so the skill and the docs server stay identical across every agent on your team. git pull in that folder picks up the latest skill.

Prefer the bare server, without the skill? Cursor reads MCP servers from mcp.json. Create .cursor/mcp.json in the project root, or ~/.cursor/mcp.json to have it everywhere:

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

Either path gives you 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:

Code
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:

json
{
  "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 your API key, or mint another there.

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:

markdown
## 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/openapi.json before using an endpoint, with the jq recipe in https://roxyapi.com/AGENTS.md. 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 `429` with code `rate_limit_per_minute` and `503` with code `compute_saturated` after the `Retry-After` seconds. Retry `500` with code `internal_error` with exponential backoff. A request that fails on our side with a `5xx` does not count against your monthly allowance, so retrying it is free. A `429` with code `rate_limit_exceeded` means the monthly allowance is used up: retrying cannot help before the reset, and `Retry-After` gives the seconds to it. Fix the request for any other `4xx`, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring `Retry-After`, so a call made through an SDK needs no second retry loop.
- 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:

Code
---
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

Why does the RoxyAPI plugin not show up in Cursor?

The folder must sit exactly at ~/.cursor/plugins/local/roxyapi, with .cursor-plugin/plugin.json directly inside it, not one level deeper. Copy or clone it there, since a symlink to a folder elsewhere is not loaded. Turn on Include third-party Plugins, Skills, and other configs in settings, then run Developer: Reload Window.

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 your API key, billed flat, 1 request to 1 quota unit, every domain included.