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 package: docs, issues, and releases. Development happens in the Naumu monorepo. Found a bug or want a tool added? .
MCP server for Naumu - access your knowledge graph from Claude Code, Cursor, and other AI coding agents
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.
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.
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.