> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Bearer + x-api-domain Headers

> The canonical auth pattern for any HTTP-based MCP client connecting to the Nudj MCP server.

Every HTTP-based MCP client — Claude Code, Cursor, ChatGPT, custom `mcp-remote` wrappers — authenticates to the Nudj MCP server with **two headers**:

```
Authorization: Bearer <YOUR_NUDJ_MCP_TOKEN>
x-api-domain:  https://<your-subdomain>.nudj.cx/api/v2/admin
```

The MCP server validates the token against Nudj's auth layer, then uses `x-api-domain` to route tool calls to the correct organisation's Admin API. **Both headers are required.**

<Info>
  stdio-based MCP clients (Claude Desktop, older Cursor) use env vars instead of headers. This page is for HTTP transports.
</Info>

## Why two headers?

The MCP server is a **single deployment** serving many organisations. The Bearer token identifies the user; the `x-api-domain` header tells the MCP server which org the user is operating on during this session. Nudj enforces that the token's claimed org matches the subdomain in `x-api-domain` — see [Bearer Token Authentication](/developer/bearer-token-auth#organisation-scoping-why-this-matters) for why.

## Generate a token

1. Sign into the admin panel at `https://<subdomain>.nudj.cx/admin`.
2. Navigate to **Settings → Developer → MCP Tokens**.
3. Click **Generate Token** and pick an RBAC scope (Viewer, Moderator, Manager, Admin, or SuperAdmin).
4. Copy the token immediately — it is shown once.

<Warning>
  MCP tokens inherit your RBAC role. A Viewer-scoped token will fail `403` on any mutation tool; match the scope to the agent's actual needs.
</Warning>

## Configure an HTTP MCP client

Most clients accept an `mcp-remote` config block. The canonical shape:

```json theme={null}
{
  "mcpServers": {
    "nudj": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.nudj.cx/mcp",
        "--header",
        "Authorization: Bearer ${NUDJ_MCP_TOKEN}",
        "--header",
        "x-api-domain: https://<your-subdomain>.nudj.cx/api/v2/admin"
      ]
    }
  }
}
```

Replace `<your-subdomain>` with your organisation's subdomain. Store the token in an env var rather than pasting it into the config directly.

## Endpoint map

| Environment | MCP URL                       | `x-api-domain`                             |
| ----------- | ----------------------------- | ------------------------------------------ |
| Production  | `https://mcp.nudj.cx/mcp`     | `https://<subdomain>.nudj.cx/api/v2/admin` |
| Development | `https://mcp-dev.nudj.cx/mcp` | `https://devapi.nudj.cx/api/v2/admin`      |
| Local       | `http://localhost:4010/mcp`   | `https://localhost:3000/api/v2/admin`      |

For local development, see [Claude Code Setup](/developer/mcp/claude-code) — the local flow needs a TLS bypass.

## Verifying the connection

Once configured, the client exposes Nudj tools in its tool catalog. Quick sanity check — ask the agent:

> "Use the Nudj MCP to list my five most recent challenges."

If auth is wrong, you'll see a `401` or `403` in the client's error log. Common causes:

* Token copied with leading/trailing whitespace
* `x-api-domain` missing the `/api/v2/admin` suffix
* Token scoped to a different org than `x-api-domain`
* Token expired (re-generate from the admin panel)

## Related

<CardGroup cols={2}>
  <Card title="Claude Code Setup" icon="code" href="/developer/mcp/claude-code">
    Full `.mcp.json` walkthrough for Claude Code specifically.
  </Card>

  <Card title="MCP Tools Reference" icon="wrench" href="/mcp-server/introduction">
    The full tool catalog exposed by the Nudj MCP server.
  </Card>
</CardGroup>