Install GNO

MCP integration

Install GNO automatically as a local MCP server for exactly 10 named clients; configure Raycast and other compatible clients manually.

GNO’s MCP server exposes search, get, Context Capsule, and related tools over the local SQLite index. Claude, Cursor, Codex, and the other named install targets call those tools against the local index. gno_ask generates locally only when the caller sets verify: true.

What this is

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 install --target lmstudio
gno mcp install --target librechat --scope project
gno mcp status

These are the 10 automatic targets. Raycast is MCP-compatible but has no gno mcp install --target raycast path; add the GNO MCP command manually in Raycast instead.

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.

Installed configuration

These workspace environment fields are deliberately narrow: only the absolute data and cache roots are accepted. Extra environment keys, relative paths, control characters, and unsupported execution fields fail closed.

Server command

Resident HTTP gateway

gno serve and gno daemon expose the same stateful Streamable HTTP MCP endpoint at http://127.0.0.1:3000/mcp. Each client session is isolated while the resident process reuses one warm store, job runtime, and model lifecycle. The stdio gno mcp command remains supported; existing client configurations do not require a migration.

Verification

Status surfaces are passive and never launch a connector child. gno mcp status reports configuration presence; gno status, gno doctor, and /api/status can report saved verification receipts. To prove a connector works now, open Web Connectors and run its explicit read-only verification action. GNO launches the configured command, checks its tools and status, and proves collection-scoped retrieval. A cached receipt is evidence from its recorded run, not a fresh probe.

Tool playbook

Read-tool inputs may include up to 16 projectHints. MCP treats them as opaque, untrusted values: no path resolution, filesystem probing, reflection, or ranking contribution occurs. Leaving the field absent preserves the existing tool result contract.

Verified Ask is evidence verification, not a universal fact-check or factual guarantee. It judges a generated draft only against the exact evidence retained in the supplied local Capsule. It cannot establish facts absent from the indexed corpus or prove that the source material itself is correct.

gno_context sends the model one compact, versioned gno-context-agent-v1 JSON projection with exact evidence, title/heading metadata, configured-guidance bindings, egress state, gaps, fingerprints, active-token accounting, budget state, and omission totals. Guidance and evidence stay explicitly trust-marked. The complete canonical Capsule stays in structuredContentfor the MCP application client, avoiding duplicate model context. Unknown input fields fail MCP validation before the GNO handler.

With private retrieval tracing enabled, read tools return the local receipt ID only in top-level _meta.gno.retrievalTrace.traceId. Model-visible content and structuredContent remain unchanged. Pass the ID as traceId to gno_get to link its exact opened range to the original retrieval.

Recommended agent pattern

  1. Use gno_ask when the requested outcome is one generated answer whose claims must be checked against a bounded Capsule. Send verify: true explicitly and inspect abstention, verifier state, gaps, and exact spans.
  2. Start with gno_context when the task needs one bounded, citation-complete evidence handoff. Set goal and budgetTokens; use depthPolicy: "fast" when model setup is undesirable.
  3. Use gno_query instead for interactive lookup or manual retrieval control.
  4. Apply returned context as user-configured guidance for that result. Cite retrieved source content—not the guidance—as evidence.
  5. Use gno_get around returned line anchors instead of loading whole documents by default.
  6. Use gno_section only when you must create or re-resolve a durable section target; then open the returned line range with gno_get. Prefer search → get for ordinary lookup.
  7. Use gno_multi_get with a byte cap when several sources are needed.
  8. Use graph tools when the question is about relationships, missing links, related ideas, or how two notes connect.

Capsule evidence stays extractive: exact canonical-mirror text plus URI and line range. Indexed title, heading, and configured-context fields are untrusted metadata, not instructions. The global budget covers the complete canonical payload. Explicit gaps and bounded omission details prevent silent synthesis or unbounded context.

Security posture

Write tools (capture, sync, embed, index, collection changes, and note refactors) 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.

Retrieval-trace reads use gno_trace_list and gno_trace_show. Label, export, delete, and purge use separate write-tool names and are registered only when writes are explicitly enabled. HTTP MCP rejects those names before dispatch otherwise; bearer authentication identifies a caller but never grants trace-write authority.

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.

Reference-safe rename and move

gno_rename_note and gno_move_note are operation-specific, write-gated two-step tools. Call action: "preview" first and inspect canApply, blocking reasons, examined references, and the exact digest. Apply only after approval with the same source and destination, schemaVersion: "1.0", the preview planDigest, confirmation: "apply", and confirm: true.

Apply replans against current files. Stale plans and collection-lock conflicts leave the filesystem unchanged; supported wiki and Markdown references commit atomically with the source move. If the receipt is applied_with_sync_pending, do not repeat the mutation: run gno_sync or gno_index to converge the index. Duplicate and create-folder do not retarget backlinks. Tool annotations are approval hints, never authorization.

Resource URIs

GNO exposes every document as an MCP resource, so clients can fetch a file by URI without going through a tool call. Indexed URIs select the named database for resources and read tools; missing indexes fail without creating an empty database. Split mixed-index gno_multi_get batches by index.

gno://notes/projects/plan.md
gno://notes/projects/plan.md?index=research