# MCP tools

The 39 tools barrel_server 1.15.1 registers on /mcp, generated from its tools/list answer (MCP 2025-06-18, captured 2026-11-14). JSON: https://barrel-db.eu/docs/reference/mcp-tools.json

## Databases and documents

### changes

Annotations: read only.

Read the changes feed from a cursor (absent = from the start). Returns the changes and the next cursor.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `since` | string | no |  |

### db_create

Annotations: idempotent.

Create (or open) a database by name.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |

### db_info

Annotations: read only.

Info about a database: document count, lineage, retention.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |

### db_list

Annotations: read only.

List the databases currently open on this node (scoped to your grant).

No arguments.

### doc_delete

Annotations: destructive.

Delete a document by id.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `id` | string | yes |  |
| `session` | string | no |  |

### doc_get

Annotations: read only.

Read a document by id.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `id` | string | yes |  |

### doc_put

Write a document (the doc object must carry its id). Optional session tags the write's provenance.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `doc` | object | yes |  |
| `session` | string | no |  |

## Query and search

### ngram_search

Annotations: read only.

Exact substring or regex search over a database's documents via a trigram index. mode literal (default) or regex; each hit carries the document id and match spans.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `query` | string | yes |  |
| `limit` | integer | no |  |
| `mode` | string | no |  |

### query

Annotations: read only.

Run a BQL query. Rows are bounded by max_rows (default 100, cap 1000); pass the returned continuation to page. SUBSCRIBE statements are rejected: use query_subscribe.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `query` | string | yes |  |
| `continuation` | string | no |  |
| `max_rows` | integer | no |  |
| `params` | object | no |  |

### query_subscribe

Start a live query from a BQL SUBSCRIBE statement. Returns a resource URI: read it for the materialized rows, subscribe to it for update notifications.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `query` | string | yes |  |
| `params` | object | no |  |

### query_unsubscribe

Annotations: idempotent.

Stop a live query by sub id.

| Argument | Type | Required | Description |
|---|---|---|---|
| `sub` | string | yes |  |

### search

Annotations: read only.

Search a database: mode bm25 or hybrid with a query string, mode vector with a query vector.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `mode` | string | yes |  |
| `k` | integer | no |  |
| `query` | string | no |  |
| `vector` | array of any | no |  |

## Branches

### branch_create

Fork a database into a branch, optionally at a changes cursor.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |
| `name` | string | yes |  |
| `at` | string | no |  |

### branch_list

Annotations: read only.

List a database's branches and its own lineage.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |

### merge

Annotations: destructive.

Merge a branch back into its parent.

| Argument | Type | Required | Description |
|---|---|---|---|
| `db` | string | yes |  |

## Spaces, sessions and handoffs

### handoff_accept

Accept a handoff by presenting its token: opens the shared space and creates a session in it (context is read in place).

| Argument | Type | Required | Description |
|---|---|---|---|
| `token` | string | yes |  |
| `agent` | string | no |  |

### handoff_complete

Complete a handoff (revokes its token by default).

| Argument | Type | Required | Description |
|---|---|---|---|
| `token` | string | yes |  |
| `notes` | string | no |  |
| `result` | any | no |  |
| `revoke` | boolean | no |  |

### handoff_create

Hand work off: issues a capability for the space and returns its token once; whoever holds the token accepts.

| Argument | Type | Required | Description |
|---|---|---|---|
| `space` | string | yes |  |
| `task_name` | string | yes |  |
| `completed` | array of any | no |  |
| `context` | any | no |  |
| `expires_at` | integer | no |  |
| `from_agent` | string | no |  |
| `from_session` | string | no |  |
| `pending` | array of any | no |  |
| `rights` | array of any | no |  |
| `to_agent` | string | no |  |

### handoff_list

Annotations: read only.

Handoffs, filtered by space, status, to_agent, from_agent (capability callers see their own space only).

| Argument | Type | Required | Description |
|---|---|---|---|
| `from_agent` | string | no |  |
| `space` | string | no |  |
| `status` | string | no |  |
| `to_agent` | string | no |  |

### session_add_message

Append a message to a session's history.

| Argument | Type | Required | Description |
|---|---|---|---|
| `content` | any | yes |  |
| `role` | string | yes |  |
| `session` | string | yes |  |
| `space` | string | yes |  |
| `metadata` | object | no |  |

### session_create

Create a working session in a space (sliding TTL).

| Argument | Type | Required | Description |
|---|---|---|---|
| `space` | string | yes |  |
| `agent` | string | no |  |
| `data` | object | no |  |
| `ttl` | integer | no |  |

### session_get_messages

Annotations: read only.

A session's messages in chronological order (since/before unix ms, limit, order asc|desc).

| Argument | Type | Required | Description |
|---|---|---|---|
| `session` | string | yes |  |
| `space` | string | yes |  |
| `before` | integer | no |  |
| `limit` | integer | no |  |
| `order` | string | no |  |
| `since` | integer | no |  |

### session_touch

Slide a session's TTL.

| Argument | Type | Required | Description |
|---|---|---|---|
| `session` | string | yes |  |
| `space` | string | yes |  |

### space_create

Create a space: a shared context database agents reach with capability tokens. Management only.

| Argument | Type | Required | Description |
|---|---|---|---|
| `label` | string | no |  |
| `owner` | string | no |  |
| `purpose` | string | no |  |
| `session_ttl` | integer | no |  |
| `vectordb` | object | no |  |

### space_grant

Issue a capability token for a space (rights: read, write, admin). The token is shown once.

| Argument | Type | Required | Description |
|---|---|---|---|
| `space` | string | yes |  |
| `expires_at` | integer | no |  |
| `label` | string | no |  |
| `rights` | array of any | no |  |
| `subject` | string | no |  |

### space_info

Annotations: read only.

The registry document of a space.

| Argument | Type | Required | Description |
|---|---|---|---|
| `space` | string | yes |  |

### space_revoke

Annotations: destructive, idempotent.

Revoke a grant of a space by token id.

| Argument | Type | Required | Description |
|---|---|---|---|
| `space` | string | yes |  |
| `token_id` | string | yes |  |

## Contexts and working sets

### context_attach

Add a context to a working set: the contexts you work with, which context_materialize and context_import can copy locally for offline use. Omit working_set to create one; the answer's id is the working set to pass next. Logical: nothing is opened or copied. Example: {"context": "otp/tools"}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `context` | string | yes | A context name (e.g. "otp/sasl") or id (ctx_...). |
| `credential_ref` | string | no | Name of a token in the node's ctx_credentials, for a remote location. |
| `mode` | string | no | Which location of the card to use. Default: local if the card has one, else remote. One of `local`, `remote`. |
| `working_set` | string | no | Working-set id (ws_...). Omit to create a new working set. |

### context_capabilities

Annotations: read only.

What a context query may look like: the accepted statement shapes with examples, the merges, the limits (contexts per query, largest LIMIT, timeouts), working-set budgets and whether the node is offline. Call it before a first context_query. No arguments.

No arguments.

### context_detach

Annotations: destructive.

Remove a context from a working set; a saved slice of it is deleted. Returns the working set. Example: {"working_set": "ws_...", "context": "otp/eunit"}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `context` | string | yes | A context name (e.g. "otp/sasl") or id (ctx_...). |
| `working_set` | string | yes | Working-set id (ws_...), from context_attach or context_working_sets. |

### context_discover

Annotations: read only.

Find contexts about a topic: every word of q must appear in a card's name, title, description or topics (a plural matches its stem). A filter, not a ranking: other contexts may still hold answers. Returns {contexts, summary}. Example: {"q": "release"}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `q` | string | yes | Words to look for, e.g. "release handling". |

### context_import

Import a published snapshot (a directory written by an export, holding manifest.json) into this node, read only, as a working-set member that answers offline for that generation. Omit working_set to create one. Example: {"dir": "/srv/export_sasl_g1"}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `dir` | string | yes | Path of the export directory on this node. |
| `name` | string | no | Local database name for the copy. Default: derived from the context and generation. |
| `working_set` | string | no | Working-set id (ws_...). Omit to create a new working set. |

### context_inspect

Annotations: read only.

Read one context card: where it lives (local db, or remote endpoint and db), title, topics, embedding. Example: {"context": "otp/sasl"}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `context` | string | yes | A context name (e.g. "otp/sasl") or id (ctx_...). |

### context_list

Annotations: read only.

List the registered contexts: named datasets, each a database on this node or on a remote Barrel server. Returns {contexts: [card]}; pass a card's name (or id) to the other context tools. Example: {"prefix": "otp/"}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `prefix` | string | no | Only names starting with this text, e.g. "otp/". |
| `unlisted` | boolean | no | Include cards registered as unlisted. Default `false`. |

### context_materialize

Save the documents a query returns into a working set so they answer offline: one frozen slice per answering context, holding exactly those documents (by id). Omit working_set to create one. A context already in the working set must be detached first. Example: {"from_query": {"query": "SELECT b.id FROM bm25_top_k('test', k => 5) AS b", "contexts": ["otp/eunit"]}}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `from_query` | object | yes | The query whose rows (by id) are saved. |
| `include` | object | no | What to copy besides documents. |
| `max_bytes` | integer | no | Refuse the slice when the fetched documents are larger than this. At least 1. |
| `working_set` | string | no | Working-set id (ws_...). Omit to create a new working set. |

### context_offline

Annotations: idempotent.

Read or switch the node's offline mode. Offline, remote contexts are skipped and never contacted; local databases, slices and snapshots still answer. Omit offline to read the mode. Example: {"offline": true}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `offline` | boolean | no | true to go offline, false to go back online. |

### context_query

Annotations: read only.

Run one BQL statement over several contexts (names or ids) or over a working set. Returns rows (or groups per context), one sources entry per context saying whether it answered and what its answer covers, and a summary: read it first. Row queries need LIMIT (<= 1000); add ORDER BY a selected field to merge rows in order. isError is true when no context answered. Example: {"query": "SELECT id, lines FROM c ORDER BY lines DESC LIMIT 10", "contexts": ["otp/tools", "otp/sasl"]}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | One BQL statement. Strings use single quotes. Shapes: see context_capabilities. |
| `contexts` | array of string | no | Context names or ids. Give this or working_set, not both. 1 to 8 items. |
| `deadline_ms` | integer | no | Deadline for the whole request, at most 60000. Default `5000`. At least 1. |
| `max_parallel` | integer | no | Remote contexts queried at once, at most 16. Default `8`. At least 1. |
| `merge` | string | no | Leave unset for the default: ordered with ORDER BY, grouped otherwise, score for comparable vector_top_k. One of `ordered`, `grouped`, `interleave`, `score`. |
| `offline` | boolean | no | true: answer from local copies only, never contact a remote server. Default: the node's offline mode. |
| `params` | object | no | Values for $name parameters in the statement. |
| `per_context_timeout_ms` | integer | no | Deadline per context, at most 60000. Default `4000`. At least 1. |
| `working_set` | string | no | A working-set id (ws_...) instead of contexts: queries its members, local copies first. |

### context_working_set_delete

Annotations: destructive.

Delete a working set and the slices it saved (imported snapshots stay). Example: {"working_set": "ws_..."}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `working_set` | string | yes | Working-set id (ws_...), from context_attach or context_working_sets. |

### context_working_sets

Annotations: read only.

List the working sets on this node with their member names, or, given working_set, read one in full: each member's mode, membership (what its answers cover), answers_offline, budget, usage and a summary. Example: {} or {"working_set": "ws_..."}.

| Argument | Type | Required | Description |
|---|---|---|---|
| `working_set` | string | no | Working-set id (ws_...), from context_attach or context_working_sets. |
