MCP tool reference

gbrain serve exposes a stdio MCP server that speaks JSON-RPC 2.0. Seventeen brain_* tools cover the read, write, graph, intelligence, and stats surfaces. This page is the canonical catalog.

The transport is stdio. Any MCP-compatible client (Claude Code, Cursor, custom rmcp clients) can connect by spawning gbrain serve and exchanging JSON-RPC over stdin/stdout. See Connect Claude Code for a worked example.

Conventions

• Slugs may be collection-qualified (<collection>::<slug>). Bare slugs resolve to the default collection or fail with Ambiguity if multiple collections expose the same slug.
• All timestamps are ISO-8601 strings. valid_from / valid_until may be null to indicate open-start or open-end intervals.
• Error responses use extended JSON-RPC codes documented in Errors.
• The MCP server enforces collection write-gates: a restoring or needs_full_sync collection rejects mutations with CollectionRestoringError before any other validation runs.

Tools at a glance

Tool	Purpose	Mutates
brain_get	Read a page	–
brain_put	Create or update a page (OCC)	✓
brain_query	Hybrid semantic + FTS5 query	–
brain_search	FTS5 keyword search	–
brain_list	List pages with filters	–
brain_link	Create a temporal link	✓
brain_link_close	Close a temporal link interval	✓
brain_backlinks	List inbound links	–
brain_graph	N-hop graph neighbourhood	–
brain_check	Contradiction detection	–
brain_timeline	Timeline entries for a page	–
brain_tags	List, add, or remove tags	✓
brain_gap	Log a knowledge gap (privacy-safe)	✓
brain_gaps	List knowledge gaps	–
brain_stats	Brain statistics	–
brain_collections	List collection status	–
brain_raw	Store raw structured data	✓

Read tools

brain_get

Get a page by slug.

Param	Type	Required	Notes
slug	string	yes	Bare or collection-qualified

Returns the rendered markdown of the page (compiled truth + timeline).

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"brain_get","arguments":{"slug":"people/alice"}
}}

Errors: NotFound, Ambiguity.

brain_search

FTS5 full-text search.

Param	Type	Required	Default
query	string	yes	–
collection	string	no	–
wing	string	no	–
limit	u32	no	10

Returns a JSON array of {slug, title, snippet, score}.

brain_query

Hybrid semantic + FTS5 query.

Param	Type	Required	Default
query	string	yes	–
collection	string	no	–
wing	string	no	–
limit	u32	no	10
depth	string	no	– (set to "auto" for progressive expansion)

Returns a ranked, fused result list with optional progressive context up to the active token budget.

brain_list

List pages with optional filters.

Param	Type	Required	Default
collection	string	no	–
wing	string	no	–
page_type	string	no	–
limit	u32	no	50

Write tools

brain_put

Write or update a page.

Param	Type	Required	Notes
slug	string	yes	–
content	string	yes	Full page markdown (frontmatter + body)
expected_version	i64	no (required for safe updates)	OCC: must match current version

Errors: Conflict on OCC violation; CollectionReadOnlyError if the target collection is not writable; CollectionRestoringError while a collection is mid-restore.

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"brain_put",
  "arguments":{
    "slug":"people/alice",
    "content":"---\ntitle: Alice\ntype: person\n---\n# Alice\n\n…",
    "expected_version": 7
  }
}}

brain_raw

Store raw structured data (API responses, JSON) for a page.

Param	Type	Required	Default
slug	string	yes	–
source	string	yes	E.g. "crustdata", "exa", "meeting"
data	object	yes	Must be a JSON object (not array/scalar)
overwrite	boolean	no	false

Per (slug, source) only one row is kept active; older rows roll over per the configured retention.

Graph tools

brain_link

Create a typed temporal link between two pages.

Param	Type	Required
from_slug	string	yes
to_slug	string	yes
relationship	string	yes
valid_from	ISO-8601	no
valid_until	ISO-8601	no

brain_link_close

Close a temporal link by its database ID.

Param	Type	Required
link_id	u64	yes
valid_until	ISO-8601	yes

brain_backlinks

List inbound backlinks for a page.

Param	Type	Required	Default
slug	string	yes	–
limit	u32	no	–
temporal	string	no	"current" (alt: "all")

brain_graph

N-hop neighbourhood graph from a page.

Param	Type	Required	Default
slug	string	yes	–
depth	u32	no	2
temporal	string	no	"current"

Intelligence tools

brain_check

Run contradiction detection on a page or all pages.

Param	Type	Required
slug	string	no (omit to scan globally)

brain_timeline

Show timeline entries for a page.

Param	Type	Required	Default
slug	string	yes	–
limit	u32	no	20

brain_tags

List, add, or remove tags on a page.

Param	Type	Required
slug	string	yes
add	string[]	no
remove	string[]	no

brain_gap

Log a knowledge gap (privacy-safe: stores query_hash, not raw query).

Param	Type	Required
query	string	yes
slug	string	no
context	string	no

The raw query is not persisted unless explicitly approved via the knowledge_gaps approval workflow. See Sensitivity contract.

brain_gaps

List knowledge gaps.

Param	Type	Required	Default
resolved	boolean	no	false
limit	u32	no	20 (max 1000)

Stats and collections

brain_stats

Brain statistics.

No parameters. Returns counts (pages, links, embeddings, gaps), the active embedding model, and schema version.

brain_collections

List collection status for MCP clients.

No parameters. Returns one entry per attached collection with state, ignore-pattern diagnostics, and recovery flags.

JSON-RPC envelope

Every tool call uses the standard MCP tools/call shape:

{
  "jsonrpc": "2.0",
  "id": <request_id>,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { ... }
  }
}

Successful responses contain a result.content array. Errors return an error.code per Errors.