Granite docs

Connect AI tools to Granite

AI assistants such as Claude, Cursor, and VS Code can read, search, and (if you allow it) edit your notes through the Model Context Protocol (MCP). Granite has no built-in assistant: you bring the tool you already use, and you decide what it may do.

Quick start (2 minutes)

For a vault that syncs with your Granite account (Pro or Business for the knowledge base; any plan for notes):

  1. In your AI tool, add a remote MCP server with this address:
    https://mcp.granite.md/mcp
    In Claude: Settings → Connectors → Add custom connector. In Claude Code: claude mcp add --transport http granite https://mcp.granite.md/mcp.
  2. The tool opens a Granite page in your browser. Sign in if asked.
  3. Choose what the tool may do (read, edit, search the knowledge base) and which vaults it may use, then select Allow.
  4. Back in the tool, ask something like “What did I write about the Lisbon trip?”.

For a folder on your computer, with no account and no internet: open the Granite desktop app, go to Settings → AI tools, pick the vault, and copy the snippet for your tool.

Synced vaults: the Granite MCP server

The server at https://mcp.granite.md/mcp speaks MCP over Streamable HTTP and signs you in with OAuth 2.1. Clients that support remote servers register themselves automatically; you only approve them.

Claude (web and desktop)

  1. Settings → Connectors → Add custom connector.
  2. Name: Granite. URL: https://mcp.granite.md/mcp.
  3. Select Connect and approve Granite in the window that opens.

Claude Code

claude mcp add --transport http granite https://mcp.granite.md/mcp

Then run /mcp in Claude Code and choose Authenticate.

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "granite": { "url": "https://mcp.granite.md/mcp" }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "granite": { "type": "http", "url": "https://mcp.granite.md/mcp" }
  }
}

Other clients and scripts

Any MCP client that supports OAuth with dynamic client registration works. Clients without OAuth can send a personal API token instead: create one in Settings → Connected apps → API tokens and send it as Authorization: Bearer gr_pat_….

A token can do only what its scopes allow. Any write scope turns on the tools that change notes; each call is still checked against the scope for its kind of change.

ScopeAllows
vaults:readReading notes, links, tags, and templates
vaults:writeReading and every change: notes, folders, and templates
notes:createNew notes (in folders that exist; with folders:create, in new ones too), also from templates
notes:editChanging, moving, and deleting notes
folders:createNew folders
folders:editRenaming, moving, and deleting folders with everything in them
templates:editAdding, changing, and deleting templates
syncReading and writing for granite sync
kb:querySearching the knowledge base

Each narrow write scope also allows reading the vault, which its changes need.

Folders on your computer: the local server

The local server runs on your computer as part of the Granite command-line tool. Install it with brew install inhaus-team/granite/granite or curl -fsSL https://granite.md/install.sh | sh on macOS and Linux, download it for Windows from granite.md/download, or use the desktop app (Granite → Install Command Line Tool…). It works on a vault folder directly, offline, and needs no account.

The easiest way: Settings → AI tools in the desktop app shows ready-made snippets with the right paths for Claude Desktop, Claude Code, Cursor, VS Code, and Windsurf. For example, Claude Desktop (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "granite-notes": {
      "command": "/Applications/Granite.app/Contents/MacOS/granite",
      "args": ["mcp", "--vault", "/Users/you/Notes"]
    }
  }
}

Add "--read-only" to the arguments to offer only the reading tools. Restart the AI tool after changing its configuration.

The desktop app's server, one vault at a time

With Run the local MCP server on in Settings → AI tools, the desktop app serves your vault folders at http://127.0.0.1:7373/mcp (every shared vault through one connection), and each vault alone on its own port: http://127.0.0.1:7374/mcp, http://127.0.0.1:7375/mcp, and so on. A vault keeps its port; change it in Tools → MCP if another program needs it. An AI tool set up with a vault's own address sees that vault and no other. Every request carries the token shown in Settings.

From the command line: granite mcp -listen 127.0.0.1:7373 -vault work=/path/to/Work -vault-listen work=127.0.0.1:7374, with the token in GRANITE_MCP_TOKEN.

Turn vaults on or off for AI tools in Settings → AI tools → Vaults, or from inside a vault with Tools → MCP in the left sidebar, which also shows that vault's address and ready-made snippets. A vault that is off is not served at all, and granite mcp -app-vaults leaves it out too.

What the tools can do

ToolWhat it doesChanges notes
list_vaultsThe vaults the tool may useNo
list_notesNotes in a folder, with a tag, or changed recentlyNo
search_notesFind notes by words, tags, pathsNo
search_knowledge_basePassages by meaning, with citations (synced vaults, Pro and Business)No
read_noteA note's text, front matter, version, and backlinksNo
get_backlinks, get_outgoing_links, list_tagsLinks and tagsNo
create_noteA new noteAdds
update_noteReplaces a note's text, only if nobody changed it since it was readYes
patch_noteAppends, prepends, or replaces text under a heading or blockYes
move_note, delete_noteRename, move, or delete (deleted notes can be restored from history)Yes
create_folderA new folder (it starts with an empty Untitled.md, as in the apps)Adds
move_folder, delete_folderRename, move, or delete a folder with everything in itYes
list_templatesThe templates in the vault's templates folderNo
create_note_from_templateA new note from a template, with {{title}}, {{date}}, and {{time}} filled inAdds
create_template, update_template, delete_templateAdd, change, or delete a templateYes

Notes are also resources at granite://vault/{vault_id}/{path}; tools that support subscriptions are told when a note changes. Two prompts help you start: daily_note and summarize_folder.

Security guidance

Troubleshooting

The tool says it is not authorized
Disconnect it in Settings → Connected apps and connect again. Make sure the address is exactly https://mcp.granite.md/mcp.
“vault_id is required”
You have more than one vault: ask the tool to call list_vaults first, or approve the tool for a single vault.
The knowledge base tool is missing or refuses
It needs a Pro or Business plan and a token or approval with “Search your knowledge base”. Files are indexed within a minute of a change.
The local server does not start
Check that the path in the snippet points to the Granite command-line tool (which granite shows where it is) and that the vault folder exists. Run granite mcp --vault /path/to/vault in a terminal to see errors.