Barrel
EN GitHub

Outils MCP

Voici tous les outils que barrel_server enregistre sur son point d’accès /mcp, avec les arguments de chacun. Utilisez cette page quand vous écrivez un client ou un prompt qui appelle les outils Barrel et avez besoin des noms et des formes d’arguments exacts. Elle est produite à partir de la réponse tools/list de barrel_server 1.15.1 (protocole MCP 2025-06-18, moteur barrel 4.5.1), capturée le 2026-11-14 : elle correspond donc à ce que voit un client.

Les descriptions des outils et des arguments sont le texte du serveur lui-même, en anglais, tel qu’un client le reçoit.

La même liste est publiée en JSON à /docs/reference/mcp-tools.json. Pour configurer le point d’accès, voir le guide MCP.

Appeler un outil

Envoyez d’abord initialize et gardez l’en-tête mcp-session-id qu’il renvoie, puis notifications/initialized. Un tools/call répond en server-sent events (trames data:) ; le résultat est un contenu texte JSON.

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"}}}'
  • Sur un serveur où auth est configuré, ajoutez Authorization: Bearer avec un token serveur ou un jeton de capacité bsp_. Le point d’accès n’accepte que des tokens bearer, ni requêtes signées ni mTLS.
  • Un jeton de capacité ne peut appeler un outil que dans son espace et selon ses droits ; un appel refusé renvoie un résultat avec isError: true, comme {"error":"forbidden","db":"notes"}.
  • Les annotations sont des indications du serveur : les outils en lecture seule ne modifient rien, les outils destructifs suppriment ou remplacent, les outils idempotents peuvent être répétés sans risque.

Bases et documents

changes

lecture seule

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

ArgumentTypeObligatoireDescription
db string oui
since string non

db_create

idempotent

Create (or open) a database by name.

ArgumentTypeObligatoireDescription
db string oui

db_info

lecture seule

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

ArgumentTypeObligatoireDescription
db string oui

db_list

lecture seule

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

Aucun argument.

doc_delete

destructif

Delete a document by id.

ArgumentTypeObligatoireDescription
db string oui
id string oui
session string non

doc_get

lecture seule

Read a document by id.

ArgumentTypeObligatoireDescription
db string oui
id string oui

doc_put

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

ArgumentTypeObligatoireDescription
db string oui
doc object oui
session string non

lecture seule

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.

ArgumentTypeObligatoireDescription
db string oui
query string oui
limit integer non
mode string non

query

lecture seule

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.

ArgumentTypeObligatoireDescription
db string oui
query string oui
continuation string non
max_rows integer non
params object non

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.

ArgumentTypeObligatoireDescription
db string oui
query string oui
params object non

query_unsubscribe

idempotent

Stop a live query by sub id.

ArgumentTypeObligatoireDescription
sub string oui

lecture seule

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

ArgumentTypeObligatoireDescription
db string oui
mode string oui
k integer non
query string non
vector tableau de any non

Branches

branch_create

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

ArgumentTypeObligatoireDescription
db string oui
name string oui
at string non

branch_list

lecture seule

List a database's branches and its own lineage.

ArgumentTypeObligatoireDescription
db string oui

merge

destructif

Merge a branch back into its parent.

ArgumentTypeObligatoireDescription
db string oui

Espaces, sessions et passations

handoff_accept

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

ArgumentTypeObligatoireDescription
token string oui
agent string non

handoff_complete

Complete a handoff (revokes its token by default).

ArgumentTypeObligatoireDescription
token string oui
notes string non
result any non
revoke boolean non

handoff_create

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

ArgumentTypeObligatoireDescription
space string oui
task_name string oui
completed tableau de any non
context any non
expires_at integer non
from_agent string non
from_session string non
pending tableau de any non
rights tableau de any non
to_agent string non

handoff_list

lecture seule

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

ArgumentTypeObligatoireDescription
from_agent string non
space string non
status string non
to_agent string non

session_add_message

Append a message to a session's history.

ArgumentTypeObligatoireDescription
content any oui
role string oui
session string oui
space string oui
metadata object non

session_create

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

ArgumentTypeObligatoireDescription
space string oui
agent string non
data object non
ttl integer non

session_get_messages

lecture seule

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

ArgumentTypeObligatoireDescription
session string oui
space string oui
before integer non
limit integer non
order string non
since integer non

session_touch

Slide a session's TTL.

ArgumentTypeObligatoireDescription
session string oui
space string oui

space_create

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

ArgumentTypeObligatoireDescription
label string non
owner string non
purpose string non
session_ttl integer non
vectordb object non

space_grant

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

ArgumentTypeObligatoireDescription
space string oui
expires_at integer non
label string non
rights tableau de any non
subject string non

space_info

lecture seule

The registry document of a space.

ArgumentTypeObligatoireDescription
space string oui

space_revoke

destructifidempotent

Revoke a grant of a space by token id.

ArgumentTypeObligatoireDescription
space string oui
token_id string oui

Contextes et ensembles de travail

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

ArgumentTypeObligatoireDescription
context string oui A context name (e.g. "otp/sasl") or id (ctx_...).
credential_ref string non Name of a token in the node's ctx_credentials, for a remote location.
mode string non Which location of the card to use. Default: local if the card has one, else remote. Une valeur parmi `local`, `remote`.
working_set string non Working-set id (ws_...). Omit to create a new working set.

context_capabilities

lecture seule

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.

Aucun argument.

context_detach

destructif

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

ArgumentTypeObligatoireDescription
context string oui A context name (e.g. "otp/sasl") or id (ctx_...).
working_set string oui Working-set id (ws_...), from context_attach or context_working_sets.

context_discover

lecture seule

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

ArgumentTypeObligatoireDescription
q string oui 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"}.

ArgumentTypeObligatoireDescription
dir string oui Path of the export directory on this node.
name string non Local database name for the copy. Default: derived from the context and generation.
working_set string non Working-set id (ws_...). Omit to create a new working set.

context_inspect

lecture seule

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

ArgumentTypeObligatoireDescription
context string oui A context name (e.g. "otp/sasl") or id (ctx_...).

context_list

lecture seule

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

ArgumentTypeObligatoireDescription
prefix string non Only names starting with this text, e.g. "otp/".
unlisted boolean non Include cards registered as unlisted. Défaut `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"]}}.

ArgumentTypeObligatoireDescription
from_query object oui The query whose rows (by id) are saved.
include object non What to copy besides documents.
max_bytes integer non Refuse the slice when the fetched documents are larger than this. Au moins 1.
working_set string non 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}.

ArgumentTypeObligatoireDescription
offline boolean non true to go offline, false to go back online.

context_query

lecture seule

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

ArgumentTypeObligatoireDescription
query string oui One BQL statement. Strings use single quotes. Shapes: see context_capabilities.
contexts tableau de string non Context names or ids. Give this or working_set, not both. De 1 à 8 éléments.
deadline_ms integer non Deadline for the whole request, at most 60000. Défaut `5000`. Au moins 1.
max_parallel integer non Remote contexts queried at once, at most 16. Défaut `8`. Au moins 1.
merge string non Leave unset for the default: ordered with ORDER BY, grouped otherwise, score for comparable vector_top_k. Une valeur parmi `ordered`, `grouped`, `interleave`, `score`.
offline boolean non true: answer from local copies only, never contact a remote server. Default: the node's offline mode.
params object non Values for $name parameters in the statement.
per_context_timeout_ms integer non Deadline per context, at most 60000. Défaut `4000`. Au moins 1.
working_set string non A working-set id (ws_...) instead of contexts: queries its members, local copies first.

context_working_set_delete

destructif

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

ArgumentTypeObligatoireDescription
working_set string oui Working-set id (ws_...), from context_attach or context_working_sets.

context_working_sets

lecture seule

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

ArgumentTypeObligatoireDescription
working_set string non Working-set id (ws_...), from context_attach or context_working_sets.
Remarque

Le schéma ne marque que query comme obligatoire pour context_query ; le serveur demande aussi l’un de contexts ou working_set. La description de db_info mentionne un nombre de documents, mais les infos renvoyées n’en contiennent pas.

Traduit de la page anglaise: /docs/reference/mcp-tools/ Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir