Bearer + x-api-domain Headers

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.

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

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 for why.

Generate a token

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

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.

Configure an HTTP MCP client

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

{
  "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 — 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)

Claude Code Setup

Full .mcp.json walkthrough for Claude Code specifically.

MCP Tools Reference

The full tool catalog exposed by the Nudj MCP server.

API Reference

Authentication & User Linking

Webhooks

MCP Server

Resources

Why two headers?

Generate a token

Configure an HTTP MCP client

Endpoint map

Verifying the connection

Claude Code Setup

MCP Tools Reference

​Why two headers?

​Generate a token

​Configure an HTTP MCP client

​Endpoint map

​Verifying the connection

​Related

Claude Code Setup

MCP Tools Reference

Why two headers?

Generate a token

Configure an HTTP MCP client

Endpoint map

Verifying the connection

Related