Connect an MCP client
On this page
Your MCP client starts notegraph as a local program and talks to it over standard input and output. There is no
network port and no login. Make your vault first with notegraph init.
The commands below pin the version: notegraph@0.0.0. An unpinned npx notegraph runs the newest
version each time the client starts. A pinned one runs the version you chose. When you upgrade, change the number
by hand.
Claude Code#
Add the server
claude mcp add notegraph -- npx -y notegraph@0.0.0 mcp
Check it with claude mcp list. To share the setup with a project, put the same command in the
.mcp.json of that project, in the form shown for Claude Desktop below.
Claude Desktop#
Add the server to claude_desktop_config.json. On macOS it is in
~/Library/Application Support/Claude/. Restart the app after you save the file. The app must be able
to find npx on its path.
claude_desktop_config.json
{
"mcpServers": {
"notegraph": {
"command": "npx",
"args": [
"-y",
"notegraph@0.0.0",
"mcp"
]
}
}
}
What your client sees#
The server offers the sixteen tools and a short set of instructions that tells the agent
its limits. Each write applies at once; there is no approval step. notegraph records the client name and version
that the client reports with every change. The client chooses that name, so it is a label and not proof of
identity. You see it in notegraph log.
Read-only mode#
For an agent that reads web pages or other untrusted text, use read-only mode. It can read and search, not write.
Read-only server
{
"mcpServers": {
"notegraph": {
"command": "npx",
"args": [
"-y",
"notegraph@0.0.0",
"mcp",
"--read-only"
]
}
}
}
Read-only mode registers only the eight read tools: read, search, backlinks,
frontmatter, graph, history, health and attachment. The core also refuses every write in that
session. For Claude Code, add --read-only after mcp in the claude mcp add
command.
Keep the agent shell away from notegraph#
The MCP tools are the way an agent should reach your vault. These rules keep its shell and file tools away from the command line, the store and the secrets. Add them to the settings of your client. This example uses the rule syntax of Claude Code; other clients have their own.
Claude Code settings.json
{
"permissions": {
"deny": [
"Bash(notegraph:*)",
"Bash(npx notegraph:*)",
"Bash(npx -y notegraph:*)",
"Bash(sqlite3:*)",
"Bash(security:*)",
"Bash(secret-tool:*)",
"Read(~/Library/Application Support/sh.notegraph/**)",
"Edit(~/Library/Application Support/sh.notegraph/**)",
"Read(~/.local/share/notegraph/**)",
"Edit(~/.local/share/notegraph/**)"
]
}
}
notegraphandnpx notegraphare the command line, which can revert, open and change what agents may see.-
The data directory holds the store and, if you chose a file for your keys,
secrets.key. It is~/Library/Application Support/sh.notegraphon macOS and~/.local/share/notegraphon Linux, unlessNOTEGRAPH_HOMEis set. sqlite3opens the store directly.security(macOS) andsecret-tool(Linux) read the OS secret store.