MCP tools
This is every tool barrel_server registers on its /mcp endpoint, with the arguments each one takes.
Use it when you write a client or a prompt that calls Barrel tools and need the exact names and argument shapes.
The page is generated from the tools/list answer of barrel_server 1.15.1 (MCP protocol 2025-06-18,
engine barrel 4.5.1), captured on 2026-11-14, so it matches what a client sees.
The same list is published as JSON at /docs/reference/mcp-tools.json.
To set up the endpoint, see the MCP guide.
Call a tool
Send initialize first and keep the mcp-session-id header it returns,
then notifications/initialized. A tools/call answers as server-sent events
(data: frames); the result is JSON text content.
curl -X POST localhost:8080/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H "mcp-session-id: $SID" \
-H 'mcp-protocol-version: 2025-06-18' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"doc_get",
"arguments":{"db":"notes","id":"note-1"}}}' - On a server with
authconfigured, addAuthorization: Bearerwith a server token or absp_capability token. The endpoint accepts bearer tokens only, not signed requests or mTLS. - A capability token can call a tool only within its space and rights; a denied call returns a result with
isError: true, such as{"error":"forbidden","db":"notes"}. - Annotations are hints from the server: read only tools change nothing, destructive tools delete or replace, idempotent tools can be repeated safely.
Databases and documents
changes
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
idempotent
Create (or open) a database by name.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes |
db_info
read only
Info about a database: document count, lineage, retention.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes |
db_list
read only
List the databases currently open on this node (scoped to your grant).
No arguments.
doc_delete
destructive
Delete a document by id.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes | |
id | string | yes | |
session | string | no |
doc_get
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
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
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
idempotent
Stop a live query by sub id.
| Argument | Type | Required | Description |
|---|---|---|---|
sub | string | yes |
search
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
read only
List a database's branches and its own lineage.
| Argument | Type | Required | Description |
|---|---|---|---|
db | string | yes |
merge
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
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
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
read only
The registry document of a space.
| Argument | Type | Required | Description |
|---|---|---|---|
space | string | yes |
space_revoke
destructiveidempotent
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
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
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
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
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
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
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
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
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
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. |
The schema marks only query as required for context_query; the server also needs one of contexts or working_set. The db_info description mentions a document count, but the info it returns has none.