# Client setup

> Configuration snippets for Claude Desktop, Cursor, VS Code with GitHub Copilot, and the OpenAI Codex CLI.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/mcp/clients

---
Drop the snippet for your client into the listed config file, restart the
assistant, and the Orangescrum tools appear automatically. Replace
`YOUR_KEY` with the partner API key issued to you from the admin portal.

> **These files hold a live credential**
>
> The key sits in plain text in every config below. Do not commit
> `.vscode/mcp.json` to a shared repository, and treat the file as you would a
> `.env`.

## Claude Desktop

**File:** `claude_desktop_config.json`

- Windows — `%APPDATA%\Claude\`
- macOS — `~/Library/Application Support/Claude/`

Claude Desktop speaks STDIO, not remote HTTP, so it spawns `npx mcp-remote` as a
bridge. **Node.js must be installed** and on the PATH.

```json
{
  "mcpServers": {
    "orangescrum": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://v4-api.orangescrum.com/mcp/partner",
        "--header",
        "X-API-KEY:YOUR_KEY"
      ]
    }
  }
}
```

> **Note**
>
> Note the header format: `X-API-KEY:YOUR_KEY` with **no space** after the colon.
> A space makes `mcp-remote` treat it as two arguments and the server returns
> `401`.

## Cursor

**File:** `~/.cursor/mcp.json`

Cursor speaks remote MCP natively and forwards custom headers as-is, so no
bridge is needed.

```json
{
  "mcpServers": {
    "orangescrum": {
      "url": "https://v4-api.orangescrum.com/mcp/partner",
      "headers": {
        "X-API-KEY": "YOUR_KEY"
      }
    }
  }
}
```

## VS Code + GitHub Copilot

**File:** `.vscode/mcp.json` in your workspace, or the user-level equivalent.

Copilot Chat picks this up automatically in **agent mode** — the tools will not
appear in ask mode.

```json
{
  "servers": {
    "orangescrum": {
      "type": "http",
      "url": "https://v4-api.orangescrum.com/mcp/partner",
      "headers": {
        "X-API-KEY": "YOUR_KEY"
      }
    }
  }
}
```

> **Tip**
>
> Add `.vscode/mcp.json` to your `.gitignore` before you paste a key into it.

## OpenAI Codex CLI

**File:** `~/.codex/config.toml`

Recent Codex releases support remote HTTP MCP servers with custom headers.

```toml
[mcp_servers.orangescrum]
url = "https://v4-api.orangescrum.com/mcp/partner"

[mcp_servers.orangescrum.headers]
X-API-KEY = "YOUR_KEY"
```

## Any other MCP client

The server is a standard JSON-RPC 2.0 MCP endpoint. Anything that can send a
`POST` with a custom header will work:

| Setting | Value |
| --- | --- |
| Transport | Remote HTTP |
| URL | `https://v4-api.orangescrum.com/mcp/partner` |
| Auth header | `X-API-KEY: YOUR_KEY` |
| Protocol | JSON-RPC 2.0 |

> **OAuth-only clients cannot connect**
>
> Browser-based clients that require an OAuth flow — including custom connectors
> on claude.ai — are not supported. The server authenticates by API key only.

## Verify the connection

Independent of any client, this proves the server accepts your key:

```bash
curl -sS -X POST https://v4-api.orangescrum.com/mcp/partner \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_KEY' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

A successful response lists all 15 tool names. If this works but your client
still shows no tools, the problem is in the client config — see
[Troubleshooting](https://helpdesk.orangescrum.com/guide/mcp/troubleshooting).