How do I install Naumu?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Naumu need an API key?

The publisher lists these environment variables: NAUMU_API_KEY, NAUMU_API_URL, NAUMU_IDENTITY_ID.

When was Naumu last checked?

Last checked 2026-10-19. Search, extend, and act on your team's Naumu knowledge graph: notes, threads, and nodes.

Naumu MCP server

Power your agent

Add this server

The publisher's own URL. Not a PlugMCP endpoint.

Add to Cursor Add in Claude Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Server URL

https://naumu.ai/api/mcp

Credentials from the publisher

NAUMU_API_KEY — Naumu API key (starts with nmu_), created in Naumu under Settings > Your agents.
NAUMU_API_URL — Override the Naumu API base URL. Defaults to https://naumu.ai.
NAUMU_IDENTITY_ID — Optional bot identity id to act as when the key covers several identities.

The Claude button above opens Claude with the name and URL filled in. You still confirm it there.

shClaude Code

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

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "ai.naumu-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "mcp-remote",8        "https://naumu.ai/api/mcp"9      ]10    }11  }12}

claude_desktop_config.json

Remote · HTTPPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Remote

Transport: http
Version: 0.19.1

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

@naumu/mcp

MCP server for Naumu - access your knowledge graph from Claude Code, Cursor, and other AI agents.

This repository is the public home of the published @naumu/mcp package: docs, issues, and releases. Development happens in the Naumu monorepo. Found a bug or want a tool added? Open an issue.

Naumu speaks MCP over two transports:

Remote, over OAuth at https://naumu.ai/api/mcp - the recommended path. You sign in through your browser, and there is no API key to create, paste, or keep in sync. This package is not involved.
Local stdio, this package, launched on demand with npx and authenticated with an API key. Use it for clients that cannot do browser OAuth: CI jobs, bot and external-agent identities, and older stdio-only harnesses.

Recommended setup: remote MCP over OAuth

Register the server once. The first time a session uses a Naumu tool, your browser opens to sign in and approve access. After that the tools are available in every session.

Claude Code

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

--scope user registers the server for your whole machine rather than the current project, so you do not have to repeat it per repository.

Cursor

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

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 clients that support remote servers follow the same shape: point them at https://naumu.ai/api/mcp and let the browser handle sign-in. Use the front-end origin (naumu.ai), not a backend address - sign-in and consent rely on your Naumu session, which lives on the front-end origin.

You can revoke a connected tool's access at any time in Naumu under Settings > Your agents, in the Active access list.

See Local MCP for the full walkthrough.

Fallback setup: local stdio server with an API key

Use this package when your client cannot do browser OAuth - CI, bots and external agent identities, or a harness that only speaks stdio.

1. Get an API key

Open Settings > Your agents in Naumu.
Select Create an API key and give it a recognizable name (such as the tool it is for).
Copy the key right away. It is shown only once and cannot be retrieved later. Keys start with nmu_.

Use a separate key per tool, so a leak only costs you that one key.

2. Configure your client

You do not install this package globally; your client launches it on demand with npx.

Claude Code

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

Cursor

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

Environment variables

Variable	Required	Default	Description
`NAUMU_API_KEY`	Yes	-	Your API key (starts with `nmu_`)
`NAUMU_API_URL`	No	`https://naumu.ai`	Naumu API base URL. You do not need to set this

Available tools

Both transports expose the same tool surface. Tools marked bot are only registered for bot identity keys (nmu_bot_*), which additionally receive a filtered subset based on the identity's permissions.

Spaces and members

Tool	Description
`naumu_list_graphs`	List every space (graph) the key can access, with ids, names, and roles
`naumu_create_graph`	Create a new, empty space owned by the authenticated user
`naumu_list_members`	List a space's members with their roles
`naumu_whoami`	Return who the calling key is (user, or bot identity with its graph and allowed tools)

Schema

Tool	Description
`naumu_get_schema`	Get a space's schema (node types, attributes, connections)
`naumu_update_schema`	Replace the schema with a full new definition
`naumu_add_node_type`	Add one node type without resending the whole schema
`naumu_add_connection`	Add one connection from an existing node type to another
`naumu_add_attribute`	Add or extend an attribute on an existing node type
`naumu_list_schema_violations`	Audit a space against its schema and report violations

Reading the graph

Tool	Description
`naumu_search`	Hybrid (meaning plus text) search over graph nodes
`naumu_filter`	Filter nodes by type and attributes, with deterministic and complete results
`naumu_get_node`	Get one node with its properties, edges, notes, threads, and generated context
`naumu_list_node_connections`	List a single node's connections
`naumu_list_dense_nodes`	Find over-connected hub nodes by child count
`naumu_ask`	Ask @Naumu a question and get a synthesised, node-grounded answer with sources and confidence

Writing to the graph

Tool	Description
`naumu_add_node`	Create 1-25 nodes in one call
`naumu_update_node`	Overwrite properties of an existing node
`naumu_remove_node`	Delete a node and all of its connections (destructive)
`naumu_add_edge`	Create 1-25 edges between existing nodes
`naumu_remove_edge`	Delete one edge identified by (source, target, label)
`naumu_remove_edges_bulk`	Delete 1-100 edges in one atomic call
`naumu_reparent`	Atomically swap a node's parent edge
`naumu_batch_reparent`	Reparent 1-25 nodes onto a shared new parent
`naumu_delegate`	Hand @Naumu a task to carry out asynchronously; returns a `threadId` to poll

Threads and topics

Tool	Description
`naumu_list_threads`	List threads by last activity, with an `isParticipant` flag
`naumu_get_thread`	Fetch one thread plus its human and bot participant rosters
`naumu_read_thread`	Read a thread's messages; each carries `processing` or `complete` status
`naumu_post_message`	Post a markdown message in a thread you participate in
`naumu_create_thread`	bot Start a new conversation, attach participants, post a first message, optionally file into topics
`naumu_add_reaction`	Add an emoji reaction to a message (idempotent)
`naumu_remove_reaction`	Remove your own reaction from a message
`naumu_typing`	Show or hide your "is typing" indicator in a thread
`naumu_list_topics`	List a space's topics (filing destinations) for use in `topicIds`
`naumu_create_topic`	Create a topic; admin-only, name must be a lowercase slug

Notes

Tool	Description
`naumu_create_note`	Create a note, optionally with its full markdown body in the same call
`naumu_note_read`	Read a note's current markdown plus the nodes it is tied to
`naumu_note_append`	Append markdown blocks to the end of a note
`naumu_note_insert`	Insert markdown immediately after a named heading
`naumu_note_replace_section`	Replace the body under a named heading
`naumu_note_delete_section`	Delete a heading and its body (destructive)
`naumu_note_replace`	Replace an entire note's content (destructive)
`naumu_note_find_replace`	Literal find and replace within a note

Attachments

Tool	Description
`naumu_request_attachment_upload`	Get a presigned S3 URL to upload a file, then reference it via `attachmentIds`
`naumu_get_attachment`	Read a chat attachment by `attachmentId`
`naumu_persist_canvas_attachment`	Promote a canvas-bound pending attachment to a persisted one

Space admission

Tool	Description
`naumu_admission_status`	Show who can auto-join a space and who is waiting for approval
`naumu_whitelist_members`	Whitelist emails so those people auto-join on sign-in
`naumu_resolve_admission`	Join (or request to join) the space a repo's `.naumu` file references
`naumu_resolve_join_request`	Approve or deny a pending join request

ChatGPT compatibility

The OpenAI MCP surface requires tools literally named search and fetch. These wrap cross-space search and node reads in the response shapes that client expects.

Tool	Description
`search`	Search across every accessible space; returns `{ results: [{ id, title, url }] }`
`fetch`	Fetch a node returned by `search`; returns `{ id, title, text, url }`

Troubleshooting

When the stdio server is misconfigured it exits before the MCP handshake, and most clients simply show no server at all, with no error. Run the built-in self-check to find out why:

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

It checks, in order, that NAUMU_API_KEY is set (the key itself is never printed), that the API is reachable and accepts the key, and that this build matches the latest published version. It prints one line per check plus a verdict, and exits non-zero if anything failed:

naumu-mcp doctor (v0.11.1, API https://naumu.ai)

[fail] API key: NAUMU_API_KEY is missing from the environment
[warn] API: reachable (https://naumu.ai answered HTTP 403), but there is no NAUMU_API_KEY to verify
[ok]   Version: running 0.11.1 (npm latest)

Verdict: 1 check failed - the MCP server will not work until this is fixed.
Most likely fix: Set NAUMU_API_KEY - create a key at https://naumu.ai/settings (Settings > Your agents > Create an API key)

Run it with the same environment your MCP client uses, otherwise the key check reports on your shell rather than on the client's configuration.

License

MIT

Naumu

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Naumu?

Does Naumu need an API key?

What transport does Naumu use?

When was Naumu last checked?

Documentation

@naumu/mcp

Recommended setup: remote MCP over OAuth

Claude Code

Cursor

Fallback setup: local stdio server with an API key

1. Get an API key

2. Configure your client

Claude Code

Cursor

Environment variables

Available tools

Spaces and members

Schema

Reading the graph

Writing to the graph

Threads and topics

Notes

Attachments

Space admission

ChatGPT compatibility

Troubleshooting

License