# MCP integration

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

Section: Reference  
Canonical: https://gno.sh/docs/mcp  
Markdown: https://gno.sh/docs/mcp.md

## 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](https://gno.sh/docs/compiled-context) 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](https://gno.sh/docs/how-search-works#complete-evidence).

## 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](https://gno.sh/docs/configuration#chunking).

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 `structuredContent`for 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](https://gno.sh/docs/api#host-paths).

## 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](https://gno.sh/docs/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](https://gno.sh/docs/cli#index-paths).

## 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](https://gno.sh/docs/skills)
- [Connect your AI tools](https://gno.sh/docs/how-to#connect-ai)

## 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.](https://gno.sh/docs/typed-metadata)

## 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](https://gno.sh/docs/sessions).