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/**)"
    ]
  }
}