# 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](https://github.com/features/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](/pricing).
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`:

```json
{
  "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:

```json
{
  "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:

```bash
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](/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:

```markdown
## 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](/docs/sdk "RoxyAPI TypeScript, Python, PHP, C#, and Go 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 <a href="/AGENTS.md" target="_blank" rel="noopener" title="AGENTS.md execution playbook for AI coding agents - tight language-agnostic guide">AGENTS.md</a> 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


### Does GitHub Copilot support remote MCP servers?
Yes. In Agent mode, Copilot connects to streamable HTTP (Remote) MCP servers defined with `"type": "http"` in `mcp.json`, on VS Code 1.101 or later. RoxyAPI runs Remote MCP over streamable HTTP, so there is no local process to install or keep running.

### How do I keep my RoxyAPI key out of the Copilot config file?
Define an input variable in the `inputs` array with `"password": true`, then reference it as `${input:roxy-api-key}` in the server `headers`. VS Code prompts for the value the first time the server starts and stores it securely, so the key never appears in `mcp.json`.

### Where do I put standing RoxyAPI instructions for Copilot?
Add them to `.github/copilot-instructions.md` in your repository. Copilot reads that file as context on every request. Every RoxyAPI SDK also ships an `AGENTS.md` that Copilot reads when the SDK is installed.

### Is RoxyAPI free to try with GitHub Copilot?
The keyless docs MCP server at https://roxyapi.com/mcp/docs needs no key and returns documentation so Copilot writes correct code before you pay. Live calls across all 12 domains need an API key from the [pricing page](/pricing), billed at a flat rate where 1 request equals 1 quota unit, every domain included.

## What to build next

- The [MCP setup docs](/docs/mcp) cover every other MCP client (Cursor, Claude Code, Codex, OpenAI Agents, Gemini Agents).
- The [Codex guide](/docs/guides/codex) and [Cursor guide](/docs/guides/cursor) use the same servers in other agents and editors.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) builds a multi-domain chatbot on top of these servers.
- The [API reference](/api-reference) lets you explore endpoints before asking Copilot to wire them up.