> ## 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.

# Claude Code Setup

> Configure Claude Code to talk to the Nudj MCP server via .mcp.json.

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.

<Info>
  This is the developer workflow. For admin-panel / Claude Desktop setup, see [MCP Admin Setup](/developer/mcp-admin-setup).
</Info>

## Prerequisites

* Claude Code installed and running in a project directory.
* An MCP token from **Settings → Developer → MCP Tokens** (see [Bearer + x-api-domain](/developer/mcp/bearer-and-domain#generate-a-token)).
* `npx` on `PATH` (comes with Node.js).

## Cloud MCP (recommended)

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

```json theme={null}
{
  "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:

```bash theme={null}
# ~/.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:

```json theme={null}
{
  "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):

```bash theme={null}
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:

```bash theme={null}
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`:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Tools never appear in the catalog" icon="eye-slash">
    * 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.
  </Accordion>

  <Accordion title="401 Unauthorized on every tool call" icon="lock">
    * Token expired or has leading/trailing whitespace. Regenerate it.
    * For local dev: check `NEXTAUTH_SECRET` matches across admin, API, and MCP `.env.local` files.
  </Accordion>

  <Accordion title="403 Forbidden" icon="user-lock">
    * 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.
  </Accordion>

  <Accordion title="Local dev: ECONNREFUSED or self-signed cert errors" icon="circle-exclamation">
    * 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).
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Bearer + Domain Headers" icon="plug" href="/developer/mcp/bearer-and-domain">
    The auth pattern shared by all HTTP MCP clients.
  </Card>

  <Card title="MCP Tools Catalog" icon="wrench" href="/mcp-server/introduction">
    Every tool the Nudj MCP server exposes.
  </Card>
</CardGroup>