Claude Code Setup

Claude Code reads MCP server configuration from a .mcp.json file at your project root. This page walks through wiring Nudj into Claude Code for both cloud-hosted and local MCP servers.

This is the developer workflow. For admin-panel / Claude Desktop setup, see MCP Admin Setup.

Prerequisites

Claude Code installed and running in a project directory.
An MCP token from Settings → Developer → MCP Tokens (see Bearer + x-api-domain).
npx on PATH (comes with Node.js).

Cloud MCP (recommended)

Add Nudj’s hosted MCP server to your project’s .mcp.json:

{
  "mcpServers": {
    "nudj-dev": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-dev.nudj.cx/mcp",
        "--header",
        "Authorization: Bearer ${NUDJ_DEV_MCP_TOKEN}",
        "--header",
        "x-api-domain: https://devapi.nudj.cx/api/v2/admin"
      ]
    }
  }
}

Then export the token in your shell so Claude Code can inject it at runtime:

# ~/.zshrc or ~/.bashrc
export NUDJ_DEV_MCP_TOKEN='paste-your-token-here'

Reload your shell and restart Claude Code. The Nudj tools should appear in the MCP tool list.

Local MCP (contributors)

If you’re iterating on the MCP server itself, point Claude Code at your local instance:

{
  "mcpServers": {
    "nudj-local": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:4010/mcp",
        "--header",
        "Authorization: Bearer ${NUDJ_LOCAL_MCP_TOKEN}",
        "--header",
        "x-api-domain: https://localhost:3000/api/v2/admin"
      ]
    }
  }
}

Then start the MCP server with TLS verification disabled (the local Nudj API uses self-signed HTTPS):

cd apps/mcp-server
NODE_TLS_REJECT_UNAUTHORIZED=0 pnpm dev

Important local-dev notes:

MCP URL is http://localhost:4010/mcp (HTTP, not HTTPS, and note the /mcp path).
x-api-domain uses https://localhost:3000/api/v2/admin — HTTPS with the full /api/v2/admin suffix.
All three apps (admin, API, MCP) must share the same NEXTAUTH_SECRET in their .env.local files, otherwise token validation will fail with 401.

Reconnecting after a config change

Claude Code caches MCP connections. After editing .mcp.json or rotating a token:

pkill -f mcp-remote    # kill the stale mcp-remote process

Then run /mcp in Claude Code to reconnect.

Combining with other MCP servers

Claude Code happily runs multiple MCP servers side by side. Common combos alongside nudj:

{
  "mcpServers": {
    "nudj-dev": { "...": "..." },
    "jira": { "...": "..." },
    "vercel": { "...": "..." }
  }
}

Each server exposes its own tools; Claude Code aggregates them. There is no cross-server interference — they run as independent subprocesses.

Troubleshooting

Tools never appear in the catalog

Confirm .mcp.json is at the project root (not inside a subdirectory).
Check Claude Code’s MCP log for startup errors.
Verify the env var holding your token is exported in the shell Claude Code inherits.

401 Unauthorized on every tool call

Token expired or has leading/trailing whitespace. Regenerate it.
For local dev: check NEXTAUTH_SECRET matches across admin, API, and MCP .env.local files.

403 Forbidden

Token is valid but its claimed organisation doesn’t match x-api-domain. Re-issue a token from the correct org’s admin panel.
Token’s RBAC scope is too low for the tool you’re calling. Regenerate at a higher scope.

Local dev: ECONNREFUSED or self-signed cert errors

Ensure you started the MCP server with NODE_TLS_REJECT_UNAUTHORIZED=0.
Verify the API is running on https://localhost:3000 (not 3100 — that’s a worktree offset).

Bearer + Domain Headers

The auth pattern shared by all HTTP MCP clients.

MCP Tools Catalog

Every tool the Nudj MCP server exposes.

API Reference

Authentication & User Linking

Webhooks

MCP Server

Resources

Prerequisites

Cloud MCP (recommended)

Local MCP (contributors)

Reconnecting after a config change

Combining with other MCP servers

Troubleshooting

Bearer + Domain Headers

MCP Tools Catalog

​Prerequisites

​Cloud MCP (recommended)

​Local MCP (contributors)

​Reconnecting after a config change

​Combining with other MCP servers

​Troubleshooting

​Related

Bearer + Domain Headers

MCP Tools Catalog

Prerequisites

Cloud MCP (recommended)

Local MCP (contributors)

Reconnecting after a config change

Combining with other MCP servers

Troubleshooting

Related