MCP tools

MCP is the surface for agents. Grounded's server exposes seventeen tools (twenty with Databox on) built around progressive disclosure — compact cards first, full records only when the task needs them — with no agent framework required. Wire it into the agents you already use with one command.

// The pattern

Progressive disclosure #

An agent searches with ground_recall and gets small ranked cards, each with a typed ID. It expands context with ground_timeline or fetches a single full record by ID with ground_get — it never has to pull whole bodies to find the one that matters.

01 / Search

ground_recall

Hybrid recall returns compact, cited cards with typed IDs and how each matched.

02 / Expand

ground_timeline

Chronological sessions around a point, when order matters more than similarity.

03 / Fetch

ground_get

The full record by typed ID — cited and traced back to its row or file path.

// The full set

The tools #

Tool	Key inputs	Does
`ground_recall`	`query, limit?, project?, sources?, lexicalOnly?, scopes?`	Cited recall cards + raw JSON to pick a typed ID. `scopes` filters the doc lane, default `["global"]`.
`ground_impact`	`subject, limit?, sources?, project?, scopes?`	Dependency pre-flight for a literal `subject` (container, port, path) — not a search. Lexical-only by construction. Crosses the doc lane citation-only when out of scope: `title`/`snippet` come back `null`, `inScope: false`. `limit` overrides source caps.
`ground_timeline`	`around?, query?, project?, window?`	Sessions around a point in time.
`ground_get`	`typedId`	Full record for `fact:`/`session:`/`doc:` id.
`ground_brief`	`agent?, project?, machine?, cwd?, query?, format?, docScopes?, timezone?`	Assemble the startup brief (markdown or JSON). `docScopes` filters the related-docs lane, default `["global"]`. `timezone` is an IANA zone for the rendered session dates, default UTC.
`ground_vision_get`	`project?`	Global + project vision.
`ground_vision_set`	`details, summary?, scope?`	Set vision for a scope — edits the one active record in place. `summary` is the short form injected at session start; `details` is the narrative, recalled but never injected.
`ground_facts_add`	`fact, scope?, category?, detail?, topicKey?, pinned?, importance?, status?, origin?`	Add a fact. Writing an existing `(scope, topicKey)` edits that fact in place rather than creating a competing row; omitted fields keep their value.
`ground_facts_update`	`id, fact?, scope?, category?, detail?, topicKey?, pinned?, importance?, status?, origin?`	Edit a fact in place by id; only provided fields change, re-embeds when text changes; set `status` to archive/restore.
`ground_facts_list`	`scope?, limit?, status?`	List facts; `status` defaults to `active` (`archived`/`all` also accepted).
`ground_facts_delete`	`id`	Delete a fact.
`ground_session_add`	`summary, details?, project?, agent?, machine?, tags?`	Log a session.
`ground_session_update`	`id, summary?, details?, project?, workspace?, agent?, machine?, tags?, source?`	Edit a session in place by id — a partial patch: omitted fields keep their stored values, and the row re-embeds only when `summary` or `details` change. Any key outside that set is rejected.
`ground_session_delete`	`id`	Delete a session (work-log entry) by id. Not reversible.
`ground_docs_ingest`	`paths[], source?, kind?, machine?, scope?, dryRun?`	Ingest docs (dry-run supported). `scope` tags the batch's lane, default `global`.
`ground_docs_prune`	`remove?`	Reconcile doc rows against disk — mark missing, or delete with `remove:true`.
`ground_health`	`{}`	Adapter, embeddings, and counts.
`ground_databox_list`	`{}`	Databox only: the boxes, each with its state (fresh, stale, unindexed, empty, error), item count and index age.
`ground_databox_schema`	`box`	Databox only: tables and columns of one box.
`ground_databox_query`	`box, sql, limit?`	Databox only: one read-only SQL statement (DuckDB dialect). `meta` carries the citation `databox:<box>` and the SQL.

Every list-shaped tool — recall, impact, facts list, sessions list, docs list — returns the same {data, meta} envelope as the HTTP API (see the envelope), so an agent can tell a truncated result from a complete one without a second call. Every tool is guarded — errors come back as text, never thrown.

// Local or remote

Transports #

The server (grounded-mcp) speaks stdio by default — the right choice for a local agent. Set GROUNDED_MCP_HTTP_PORT and it serves a streamable HTTP transport instead, for remote or multi-agent setups.

// Copy-paste config

Wiring an agent #

Print a ready-made config snippet for your agent and drop it in. Targets: claude-code, codex, cursor, and generic.

mcp install ~

>grounded mcp install codex

[mcp_servers.grounded]

command = "grounded-mcp"

# → ~/.codex/config.toml

// Briefs on startup

Startup hooks #

To inject a brief automatically when an agent session starts, grounded hooks print emits a SessionStart wrapper that curls POST /brief, extracts the text, and hands it to the agent — failure-silent, so a down service never blocks a session. Wiring is provided per target.