MCP integration

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

Compiled project context

The full profile exposes gno_context_compiled_preview and gno_context_compiled_check with inline inputs and no server file writes. Read the compiled context guide for limits, indexed freshness, inclusion, and recovery.

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.

For multi-source answers, retrieve every required passage with gno_get or gno_multi_get and cite its URI and lines. A document hit alone is not complete evidence. Use gno_query_diagnose for a known missing target; preserve Capsule gaps and omissions and state unanswered parts or abstain when support is missing. See evidence completeness limits.

What this is

• Read tools — search, vector search, hybrid query, deterministic Context Capsules, opt-in verified Ask, document fetch, Knowledge Delta reads, scoped memory recall, tags, status, egress checks, links, backlinks, similar docs, graph exploration, integrity audits, session-archive status, and job inspection. There are 38 read-only tools by default; the opt-in core profile advertises 7 of them, selected at runtime with gno mcp --tool-profile core or once per client with gno mcp install --target <client> --tool-profile core.
• Write tools — capture notes, remember facts, add/remove collections, sync, embed, index, workspace edits, egress policy changes, private-trace mutations, manual session import, and running a session automation profile. All 21 are disabled by default. Enabling writes also registers the read-only gno_request_status lookup, for 60 tools total; the core profile adds only gno_capture and gno_remember.
• 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 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

• GNO records the absolute Bun executable and the entrypoint inside the package that performed the install. It does not depend on a desktop client finding gno on PATH, nor does it invoke bunx later.
• The active --index and absolute --config path are included in the server arguments. Absolute GNO_DATA_DIR and GNO_CACHE_DIR roots are included as env for standard MCP clients and as environment for OpenCode.
• Codex uses its official ~/.codex/config.toml at user scope and .codex/config.toml at project scope. OpenCode uses its canonical opencode.json or existing opencode.jsonc. LibreChat installation is project-only and writes the project’s librechat.yaml.

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

• 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.

Installed stdio commands run as standalone processes and unload their local models when the server exits. They do not connect to a running daemon.

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 its store, job runtime, and adapter model lifecycle. Models load lazily; warm reuse lasts only until their idle grace expires (five minutes by default), and the next inference reloads. Metadata calls do not renew that grace. The stdio gno mcp command is still supported.

• gno serve is always loopback-only because it also exposes the browser and full REST API.
• Only gno daemon accepts an explicit non-loopback bind, and only with a restrictive bearer-token file plus exact Host and Origin allowlists.
• Bearer authentication never grants write access. Mutating MCP tools still require the separate --mcp-enable-write option.
• /api/resident/status and serve|daemon --status --json expose only redacted lifecycle and capacity data—never paths, tokens, queries, content, or caller identity. Full /api/status includes local index and configuration details, so a daemon serves it only on loopback.
• The egress check for a tool call covers the collections it names: a search with collections is checked against just those collections. A call naming a collection that is not configured gets the tool's Collection not found error.
• Read tools answer while a sync, embed, or index job is writing, and see only what that job has already committed.

Cancelling an MCP request or disconnecting stops its inference and discards any late result. Model work that is already running keeps its capacity until it finishes. After a model failure, GNO does not replay queued requests; send them again. An async job keeps running after the client that started it disconnects, once the job ID was returned. It stops when you cancel the job or shut down the server.

Resident HTTP boundary errors retain HTTP 429 for rate, request, queue, or session pressure and HTTP 503 for shutdown, revoked credentials, or unavailable runtime. Authentication and write/egress checks remain separate.

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.

gno mcp status accepts client settings that do not change how the server starts, such as Claude Code’s type: "stdio", a timeout, a description or an approval list. A registration switched off with enabled: false or disabled: true shows as not configured. Settings that change how it starts, such as cwd, a URL or extra environment variables, show as malformed and are never verified.

gno doctor (mcp-runtime) and gno status (under Bun runtime) also list registrations whose Bun or GNO path no longer exists or whose Bun is older than 1.4.1, each with the gno mcp install --target <client> --force command that repairs it. A registration on a different, supported Bun is listed for information.

gno_status also returns chunking with configured/applied parameters, layout state, and pending document/mirror counts. Reading status never starts a rebuild. Write-enabled sync/index tools use the configured index-wide policy; source freshness, layout readiness, and embedding backlog are separate. See chunking configuration.

Search-tool candidate budgets apply after supported collection/path, tag, date, author, category, exclusion, visibility, and memory owner filters. Vector and hybrid retrieval select matching-language chunks; standalone lexical language remains reserved. Caller scope intersects filters and empty allowlists deny all. Score thresholds, deduplication, and limited eligible coverage may still return fewer than the limit. Hybrid vectorsUsed is true only if a vector search succeeded, even when it found no matches; wholly lexical fallback reports mode: "bm25_only". Report a local model failure as a failure, never as a semantic no-match.

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.

Every tool rejects argument names it does not declare. A misspelled key such as colection or derived_from returns an error naming that key and the tool does nothing, so a typo cannot widen a search or skip a write check.

• gno_context — compile one deterministic, token-budgeted evidence Capsule with exact line spans, provenance, coverage gaps, omissions, and capability fallbacks. Use gno_context_verify before reusing a saved Capsule. GNO never saves Capsules implicitly.
• gno_changes, gno_diff, and gno_impact — read bounded metadata-only history, retained structural diffs, and explainable dependency paths. These are read-only and share the CLI, REST, and SDK contracts.
• gno_ask — generate from one closed Context Capsule and verify every substantive claim against exact retained spans. The input object is closed and requires literal verify: true. It reports supported, contradicted, insufficient, and uncertain claims; drafts below 100% support are withheld. This is read-only and does not grant trace or corpus mutation authority.
• gno_query — default for most questions. Hybrid retrieval returns URIs, snippets, scores, line anchors, and optional context guidance. Default snippets skip leading YAML frontmatter and prefer document prose.
• gno_search — exact phrases, identifiers, filenames, and error strings you already have verbatim; a question, or a name or topic taken from it, goes to gno_query with fast. File-backed hits include source.absPath over stdio; Streamable HTTP callers never receive host paths and use the uri and relPath.
• 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_section — create or resolve a durable SectionTargetV1 when citation identity matters after edits. Not the default retrieval path. Follow exact/recovered citation lines with the tool's ready-to-use gno_get guidance (fromLine = lineStart; lineCount = lineEnd - lineStart + 1); never cite ambiguous, stale, or missing results.
• gno_links, gno_backlinks, gno_similar, gno_graph, gno_graph_neighbors, gno_graph_path — navigate relationship context.
• gno_peek — cheap peek@1.0 snapshot (counts, backlog, 10 recents with docid, plus absPath over stdio, pid-file serve detection). Same payload as gno peek --json. serve.running is true only for gno serve --detach.
• gno_status, gno_list_tags, gno_job_status, gno_list_jobs — diagnose what exists or inspect async work. In gno_status, a collection whose folder is missing or unreadable carries rootError ({ code, message }, no path), its text line reads Root unavailable: ..., and healthy is false; its documents stay indexed. If the index holds a collection the server's config does not list, other tools refuse with an error naming it until you add it back or run gno cleanup; gno_status and gno_peek still answer.
• gno_list_metadata — typed metadata keys with types, document counts and common values (collection, values 1-100). Call it before writing a filter on metadata you have not seen.
• gno_capture, gno_sync, gno_embed, gno_index, gno_add_collection, gno_remove_collection, gno_rename_note, and gno_move_note — write-enabled operations.

gno_search, gno_vsearch, and gno_query take collection for one collection or collections (1 to 256 names) to search several at once, for example collections: ["work", "ops"]. The filter applies before the result limit, so other collections never take result slots, and the response lists the searched collections in meta.collections. Sending both, an empty list, or more than 256 names is a VALIDATION error, and unknown names are listed in the error. gno_query_diagnose takes one collection.

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-v2 JSON projection with exact evidence, title/heading metadata, configured-guidance bindings, egress state, gaps, fingerprints, active-token accounting, budget state, and omission totals. Each evidence entry ends with its content date (the document's own date, such as a frontmatter date or a memory fact's record date, never the file modification time) and, for a memory fact a newer fact superseded, the successor's URI; both are null when absent, so an agent does not cite an outdated fact as current. 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 are rejected.

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. Without that, HTTP MCP rejects them. Bearer authentication identifies a caller but never grants trace-write authority.

Host absolute paths reach stdio callers only. Every Streamable HTTP caller (gno serve or gno daemon /mcp, loopback or not) gets results without source.absPath, top-level absPath, similar[].absPath, or peek recent[].absPath, and a gno:// resource read names the collection-relative path on its source: line. Over HTTP, gno_status also leaves out configPath, dbPath, and each collection's root path, and its text summary drops the config and database lines. Use the uri and relPath with gno_get to open a result. See Host paths and remote callers.

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 (stdio only), 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.

gno_capture and gno_remember (add or supersede) accept an optional requestId; check one with gno_request_status (registered with --enable-write on the full profile) before retrying. See Retry-safe writes.

Reindexing: some files, and the queue

gno_sync (files only) and gno_index (files plus embeddings) need --enable-write and run as background jobs. Both accept paths to re-read only some files of one collection (at most 256), given relative to its root or as absolute paths inside it:

collection: "notes"
paths: ["meeting.md", "projects/plan.md"]

• A listed file that no longer exists is removed from the index.
• paths needs collection and cannot be combined with gitPull or runUpdateCmd.
• An empty list, more than 256 paths, a directory, a path outside the collection (including through a symlink), or a path the collection's pattern, include, or exclude rules leave out is rejected (INVALID_INPUT or INVALID_PATH) before anything is queued.

A reindex request that arrives while another job runs is queued instead of refused: the result has status: "queued" and a jobId, and the pass starts when the jobs ahead of it finish. With nothing running, it starts at once (status: "started").

• Requests for the same collection that arrive while one is waiting join it and return its jobId, so any number of requests cause at most one more pass. Listed files are added to the pass, and a whole-collection request widens it to the whole collection. Whole-collection requests with different gitPull or runUpdateCmd settings stay separate passes.
• gno_job_status reports queued until the pass starts, plus the merged scope.
• At most 64 different passes wait at once; another returns QUEUE_FULL. Retry after the running job finishes.
• If another process holds the index write lock, a sync that would start at once returns LOCKED, and a queued pass that cannot get the lock fails with LOCKED in its job status.
• The queue lives in the server process. Passes still waiting when it stops do not run, and their job ids are unknown after a restart; the index stays consistent.
• Only reindexing queues. gno_embed and gno_add_collection still return JOB_CONFLICT while a job runs; gno_capture waits for the write lock and returns LOCKED if it stays busy.

From the CLI, gno index <collection> --path <file...> reindexes the same way; see gno index --path.

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

Related

• Agent skills reference
• Connect your AI tools

Typed metadata filters

gno_search, gno_vsearch, gno_query, gno_ask, and gno_context accept filter as a typed JSON object. Never silently remove a requested predicate when no results match; inspect coverage warnings and diagnose the expected target first.

Read the metadata guide: examples, operators, missing fields, limits, and recovery.

Agent session archive

A server started on the dedicated archive config and index exposes gno_sessions_status (read, including automation status), plus gno_sessions_import and gno_sessions_automation_run (write, requires --enable-write) in the full profile; none is in core. Import names a registered source ID with optional dryRun and limit; paths and other keys are rejected, and there is no MCP discovery tool, so remote clients never learn host directories. gno_sessions_automation_run takes a configured profileId only and returns the shared run object (ran, outcome complete, up_to_date, partial, failed, or not_started with a reason such as busy, pending, and one import receipt per source). It cannot switch on hooks or schedules, add sources, or change destinations: those are local owner actions. Connecting a client never imports its sessions. Sources added or removed with gno sessions source add or remove while the server runs show in gno_sessions_status and can be imported without a restart; a config file the server cannot read returns SESSIONS_RUNTIME_FAILURE instead of stale sources. Read the session archive guide.