Reference

MCP integration

Install GNO as a local MCP server for Claude Desktop, Claude Code, Cursor, Codex, Zed, Windsurf, Amp, and more.

MCP lets AI assistants call local tools. GNO’s MCP server gives Claude, Cursor, Codex, and other clients grounded access to your own documents without uploading the corpus to a hosted search service. GNO retrieves; the client model synthesizes.

What this is

Read tools — search, vector search, hybrid query, document fetch, tags, status, links, backlinks, similar docs, and graph exploration.
Write tools — capture notes, add/remove collections, sync, embed, and index. These are disabled by default.
Resources — documents addressable as gno:// URIs for precise follow-up reads.

Install

gno mcp install --target claude-desktop
gno mcp install --target claude-code
gno mcp install --target cursor
gno mcp install --target codex
gno mcp install --target zed
gno mcp install --target windsurf
gno mcp install --target opencode
gno mcp install --target amp
gno mcp status

Default scope is user-level when the client supports it. Use --scope project for project-local configuration in clients such as Claude Code, Cursor, Codex, OpenCode, and LibreChat. Restart the client after install.

Server command

gno mcp or gno mcp serve — run the stdio MCP server directly.
gno mcp install — write the selected client config.
gno mcp uninstall — remove GNO from a client config.
gno mcp status — inspect configured targets.
--enable-write or GNO_MCP_ENABLE_WRITE=1 — allow mutating tools.

Tool playbook

gno_query — default for most questions. Hybrid retrieval returns URIs, snippets, scores, and line anchors.
gno_search — exact phrases, titles, identifiers, and error strings.
gno_vsearch — conceptual matches where wording may differ.
gno_get and gno_multi_get — retrieve exact context after search. Prefer bounded line ranges when available.
gno_links, gno_backlinks, gno_similar, gno_graph, gno_graph_neighbors, gno_graph_path — navigate relationship context.
gno_status, gno_list_tags, gno_collections_list — diagnose what exists before searching.
gno_capture, gno_sync, gno_embed, gno_index, gno_add_collection, gno_remove_collection — write-enabled operations.

Recommended agent pattern

Start with gno_query for broad questions.
Use gno_get around returned line anchors instead of loading whole documents by default.
Use gno_multi_get with a byte cap when several sources are needed.
Use graph tools when the question is about relationships, missing links, related ideas, or how two notes connect.

Security posture

Write tools (capture, sync, embed, index, collection changes) are disabled by default so your AI client cannot accidentally modify the corpus. Enable them explicitly per client:

gno mcp install --target cursor --enable-write
GNO_MCP_ENABLE_WRITE=1 gno mcp

Collection creation rejects dangerous roots such as /, ~, system folders, and hidden config directories. Still review client approval prompts before write calls.

Capture

gno_capture is registered only when write tools are enabled. It writes structured source: frontmatter, syncs the file for FTS, accepts the same typed presetId values as CLI/REST/SDK capture, and returns the same provenance receipt shape as CLI, REST, and SDK capture, plus legacy MCP fields such as docid, absPath, overwritten, and serverInstanceId.

{
  "collection": "notes",
  "content": "thought to remember",
  "source": {
    "kind": "web",
    "url": "https://example.com/source",
    "title": "Source page"
  },
  "collisionPolicy": "open_existing",
  "presetId": "source-summary",
  "tags": ["inbox", "research"]
}

Collision checks include indexed documents and disk-only files. Use open_existing to return an existing receipt without rewriting, create_with_suffix to create the next available path, or legacy overwrite: true to replace the target path. Content must be text, and non-overwrite captures fail instead of replacing a late-arriving file. MCP capture does not auto-embed; run gno_embed or gno_index afterward when vector search should include the note.

Resource URIs

GNO exposes every document as an MCP resource, so clients can fetch a file by URI without going through a tool call.

gno://documents/<id>
gno://collections/<name>