Local MCP

Let Naumu hand you the setup

If you're already in Naumu, you don't have to copy anything out of this page. Mention in chat that you work in a coding agent and Naumu drops a setup card into its reply: buttons that open the whole setup prompt straight in Claude Code, Codex, or Claude Code for VS Code, a Copy prompt action for anything else, and the full prompt underneath so you can read it before you run it.

The prompt does more than register the server - it also installs the naumu skill and, in a repository, wires the repo into your team's space. That longer story is the Repo quickstart. If you just want the server registered by hand, the sections below are the short path.

Claude Code

Register the server once, scoped to your user, over HTTP:

claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp

--scope user is what makes the server available everywhere. Without it Claude Code registers Naumu only for the directory you ran the command in, and /mcp shows nothing in any other project.

Claude Code reads its MCP config at startup, so start a new session after adding the server, then run /mcp to check that naumu is listed and finish the browser sign-in from there.

The first time a session uses a Naumu tool, Claude Code opens your browser to sign in and approve access. After that, Naumu's tools are available in every Claude Code session - no key, no environment variable.

Cursor

Add the server to your Cursor MCP settings by its remote URL:

{
  "mcpServers": {
    "naumu": {
      "url": "https://naumu.ai/api/mcp"
    }
  }
}

Put this in ~/.cursor/mcp.json to make Naumu available in every project. A project's own .cursor/mcp.json works too, but scopes the server to that one repository. The global file is the one to use unless you deliberately want Naumu in a single project.

After saving, reload or restart Cursor and check its MCP list for naumu before you expect the tools to appear.

Cursor prompts you to sign in and approve access the first time it reaches the server. Leave any OAuth client ID and secret fields blank - Naumu registers the client for you automatically during sign-in, using Dynamic Client Registration (DCR).

Other MCP-capable agents that support remote servers follow the same shape: point them at https://naumu.ai/api/mcp and let the browser handle sign-in. Codex has its own page - see Codex.

To confirm a setup worked, keep Settings → Your agents open while you connect: the setup snippet shows a waiting state that flips to a live Connected badge the moment your tool first reaches Naumu, so you never have to guess whether the registration took.

Revoke access

You can cut off a connected tool's access at any time in Naumu, under Settings → Your agents, in the What has access list. Revoking takes effect immediately, and you don't need to remove the connector in the tool first.

API keys, CI, and fallback

Some clients can't do browser OAuth: CI jobs, bot and external-agent identities, and harnesses that only speak the older stdio MCP transport. For those, Naumu still issues API keys and publishes a local stdio server, @naumu/mcp, on npm. You don't install it globally; your agent launches it on demand with npx.

Get an API key

1. Open Settings → Your agents and find the Manual setup section.
2. Select Create API key and give the key a recognizable name (such as the tool it's for).
3. Copy the key right away - it's shown only once and cannot be retrieved later. Keys start with nmu_.

The key lets the local server act in Naumu as you, with your exact permissions. You can revoke it at any time from the same screen; see Account settings for more.

Run the stdio server

Point any stdio-capable client at npx -y -p @naumu/mcp naumu-mcp with NAUMU_API_KEY set in the environment. Claude Code, for example:

claude mcp add naumu -s user \
  -e NAUMU_API_KEY=nmu_your_key_here \
  -- npx -y -p @naumu/mcp naumu-mcp

The equivalent Cursor configuration:

{
  "mcpServers": {
    "naumu": {
      "command": "npx",
      "args": ["-y", "-p", "@naumu/mcp", "naumu-mcp"],
      "env": {
        "NAUMU_API_KEY": "nmu_your_key_here"
      }
    }
  }
}

Environment variables

If the server doesn't show up

A misconfigured stdio setup usually fails silently - the server just never appears in your client's MCP list. The package ships a self-check that diagnoses the common causes (missing key, wrong key, unreachable API, stale install):

npx -y -p @naumu/mcp naumu-mcp doctor

Run it with the same NAUMU_API_KEY your client uses and it reports what's wrong in plain terms.

Related

• Codex - connect OpenAI's Codex CLI over the same remote MCP server.
• Claude - connect claude.ai over a remote MCP connector.
• Account settings - create and revoke the API keys CI jobs and bots use.
• Search - how the search tools rank results across your spaces.