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.
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ù
authest configuré, ajoutezAuthorization: Beareravec 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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui | |
since | string | non |
db_create
idempotent
Create (or open) a database by name.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui |
db_info
lecture seule
Info about a database: document count, lineage, retention.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui | |
id | string | oui | |
session | string | non |
doc_get
lecture seule
Read a document by id.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui | |
doc | object | oui | |
session | string | non |
Requêtes et recherche
ngram_search
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui | |
query | string | oui | |
params | object | non |
query_unsubscribe
idempotent
Stop a live query by sub id.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
sub | string | oui |
search
lecture seule
Search a database: mode bm25 or hybrid with a query string, mode vector with a query vector.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui | |
name | string | oui | |
at | string | non |
branch_list
lecture seule
List a database's branches and its own lineage.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
db | string | oui |
merge
destructif
Merge a branch back into its parent.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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).
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
token | string | oui | |
agent | string | non |
handoff_complete
Complete a handoff (revokes its token by default).
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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).
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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).
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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).
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
session | string | oui | |
space | string | oui |
space_create
Create a space: a shared context database agents reach with capability tokens. Management only.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
space | string | oui |
space_revoke
destructifidempotent
Revoke a grant of a space by token id.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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/"}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"]}}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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"]}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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_..."}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
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_..."}.
| Argument | Type | Obligatoire | Description |
|---|---|---|---|
working_set | string | non | Working-set id (ws_...), from context_attach or context_working_sets. |
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.