GitHub Copilot, connect Roxy as an MCP server

Add Roxy to Copilot agent mode with one mcp.json block, then build spiritual-data features in natural language. Remote MCP, no local server to run. Time to ship: 5 minutes.

GitHub Copilot in agent mode connects to MCP servers, so it can call real tools while it writes code. RoxyAPI runs as a Remote MCP server over streamable HTTP, so Copilot 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.

This guide covers Copilot in VS Code, the most common surface. The same mcp.json shape works in the other Copilot clients that support MCP.

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 Copilot picks the right tool per question, a transit, a tarot pull, or a nakshatra, across all 12 domains under one key

What you need, 30 seconds

1. A Roxy API key. Get one on the pricing page.
2. A GitHub Copilot subscription and VS Code 1.101 or later, which is required for Remote MCP support.

Step 1, add the docs server (keyless)

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

Copilot reads MCP servers from mcp.json. Create .vscode/mcp.json in your workspace (or run MCP: Open User Configuration from the Command Palette to add it for every project) and add the docs server. Note the top-level key is servers:

{
  "servers": {
    "roxy-docs": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/docs"
    }
  }
}

Open the Chat view, switch to Agent mode, and 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 Copilot 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 in the X-API-Key header. Define an input variable so VS Code prompts for the key once and stores it securely, instead of writing it into the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "roxy-api-key",
      "description": "RoxyAPI key",
      "password": true
    }
  ],
  "servers": {
    "roxy-docs": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/docs"
    },
    "roxy-astrology": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/astrology",
      "headers": { "X-API-Key": "${input:roxy-api-key}" }
    }
  }
}

Add another roxy-<domain> block for any other domain you need: numerology, tarot, vedic-astrology, human-design, forecast, biorhythm, iching, crystals, dreams, angel-numbers, or location. Reuse the same ${input:roxy-api-key} so VS Code asks for the key only once.

Step 3, verify the connection

Run MCP: List Servers from the Command Palette (Shift+Cmd+P). Each configured server should show as running with its tool count. In the Chat view, switch to Agent mode and select the Configure Tools button to see the Roxy tools and toggle them on.

Out-of-band smoke test:

curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: YOUR_KEY"

If that prints JSON, the key is fine. If it returns 401, re-check at your account.

Step 4, first prompt to try

In Agent mode, try one of these natural-language requests. Copilot 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 copilot-instructions.md

Copilot reads .github/copilot-instructions.md as standing repository instructions on every request. Drop this block in 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, which Copilot reads automatically when the SDK is installed. For projects without an SDK, point Copilot at the site-level AGENTS.md at https://roxyapi.com/AGENTS.md, the tight, language-agnostic execution playbook with Rule 0, common task body shapes, and the field gotcha table. Copilot then understands every endpoint, parameter, and response shape on every prompt.

Gotchas

• servers, not mcpServers. VS Code mcp.json uses a top-level servers object. Remote servers set "type": "http" and a url; local stdio servers use command.
• VS Code 1.101 or later. Remote MCP and OAuth need a current VS Code. Update if MCP: List Servers does not appear.
• Use input variables for the key. Define an inputs entry with "password": true and reference it as ${input:roxy-api-key} in headers, so the key is stored securely and never committed in mcp.json.
• X-API-Key, not Authorization Bearer. Roxy uses a custom header. Put the key under headers as X-API-Key.
• Agent mode required. MCP tools are available in Agent mode, not Ask mode. Switch the chat mode selector to Agent.
• Geocode first for chart endpoints. Natal chart, kundli, panchang, and synastry all need latitude, longitude, and timezone. Tell Copilot 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 Codex guide and Cursor guide use the same servers in other agents and editors.
• The AI chatbot tutorial builds a multi-domain chatbot on top of these servers.
• The API reference lets you explore endpoints before asking Copilot to wire them up.