Barrel
FR GitHub

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.

Shell
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 auth configured, add Authorization: Bearer with a server token or a bsp_ 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.

ArgumentTypeRequiredDescription
db string yes
since string no

db_create

idempotent

Create (or open) a database by name.

ArgumentTypeRequiredDescription
db string yes

db_info

read only

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

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
db string yes
id string yes
session string no

doc_get

read only

Read a document by id.

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
db string yes
doc object yes
session string no

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.

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
db string yes
query string yes
params object no

query_unsubscribe

idempotent

Stop a live query by sub id.

ArgumentTypeRequiredDescription
sub string yes

read only

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

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
db string yes
name string yes
at string no

branch_list

read only

List a database's branches and its own lineage.

ArgumentTypeRequiredDescription
db string yes

merge

destructive

Merge a branch back into its parent.

ArgumentTypeRequiredDescription
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).

ArgumentTypeRequiredDescription
token string yes
agent string no

handoff_complete

Complete a handoff (revokes its token by default).

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
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).

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
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).

ArgumentTypeRequiredDescription
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).

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
session string yes
space string yes

space_create

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

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
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.

ArgumentTypeRequiredDescription
space string yes

space_revoke

destructiveidempotent

Revoke a grant of a space by token id.

ArgumentTypeRequiredDescription
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"}.

ArgumentTypeRequiredDescription
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"}.

ArgumentTypeRequiredDescription
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"}.

ArgumentTypeRequiredDescription
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"}.

ArgumentTypeRequiredDescription
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"}.

ArgumentTypeRequiredDescription
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/"}.

ArgumentTypeRequiredDescription
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"]}}.

ArgumentTypeRequiredDescription
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}.

ArgumentTypeRequiredDescription
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"]}.

ArgumentTypeRequiredDescription
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_..."}.

ArgumentTypeRequiredDescription
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_..."}.

ArgumentTypeRequiredDescription
working_set string no Working-set id (ws_...), from context_attach or context_working_sets.
Note

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.

Written for the site View as Markdown

Up and down to moveEnter to open