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):

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.
The tool opens a Granite page in your browser. Sign in if asked.
Choose what the tool may do (read, edit, search the knowledge base) and which vaults it may use, then select Allow.
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)

Settings → Connectors → Add custom connector.
Name: Granite. URL: https://mcp.granite.md/mcp.
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 (scopes vaults:read, vaults:write, kb:query) and send it as Authorization: Bearer gr_pat_….

Folders on your computer: the local server

The local server runs on your computer as part of the Granite command-line tool, which the desktop app installs (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.

What the tools can do

Tool	What it does	Changes notes
`list_vaults`	The vaults the tool may use	No
`list_notes`	Notes in a folder, with a tag, or changed recently	No
`search_notes`	Find notes by words, tags, paths	No
`search_knowledge_base`	Passages by meaning, with citations (synced vaults, Pro and Business)	No
`read_note`	A note's text, front matter, version, and backlinks	No
`get_backlinks`, `get_outgoing_links`, `list_tags`	Links and tags	No
`create_note`	A new note	Adds
`update_note`	Replaces a note's text, only if nobody changed it since it was read	Yes
`patch_note`	Appends, prepends, or replaces text under a heading or block	Yes
`move_note`, `delete_note`	Rename, move, or delete (deleted notes can be restored from history)	Yes

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

Give the least access that works. Allow only reading unless the tool needs to edit, and limit it to the vaults it needs. For local vaults, use --read-only when you can.
Notes can contain instructions. An AI tool reads your notes, and text in a note (for example, pasted from a web page) can try to steer it (“prompt injection”). Review changes the tool proposes, and prefer tools that ask before running write tools.
Edits never overwrite silently. update_note needs the version the tool read; if you or a synced device changed the note in between, the edit fails instead of losing your text. Every change is in the note's history, and deleted notes can be restored.
You can take access back at any time. Settings → Connected apps lists every connected tool; Disconnect stops it at once. API tokens can be revoked there too.
Keep tokens secret. Personal API tokens (gr_pat_…) are shown once; store them in a password manager or secret store, never in notes or code. If one leaks, revoke it right away.
What Granite records. Each tool call by a connected app is logged with the tool's name and time (never your note text), so you and your workspace admin can see what happened.
Workspace rules. A workspace admin can let AI tools only read the workspace's vaults, or turn them off there. Your personal vaults are not affected.
Where your notes go. The AI tool sends what it reads to its own model provider under that provider's terms. Granite itself does not call any AI model.

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 (Granite → Install Command Line Tool…) and that the vault folder exists. Run granite mcp --vault /path/to/vault in a terminal to see errors.