Barrel
EN GitHub

Point d’accès MCP

barrel_server monte un point d’accès MCP (Streamable HTTP) sur /mcp : des outils pour les bases, les documents, BQL, la recherche, la timeline, la couche agents et les contextes, ainsi que des ressources avec abonnements aux requêtes live. Lisez ce guide quand un client MCP (un runtime d’agents, un IDE, barrel_mcp_client) doit parler directement à barrel.

Quand l’utiliser

  • Vos agents accèdent à barrel par un runtime MCP plutôt qu’en REST.
  • Vous voulez que les requêtes live soient poussées aux clients sous forme de notifications de ressource mise à jour.
  • Vous donnez aux agents des jetons de capacité limités à un espace et voulez la même limitation sur la surface MCP.

Activer et configurer

Le point d’accès est actif par défaut dans le build serveur. Configurez-le avec l’env applicatif {barrel_server, mcp, #{...}} :

{barrel_server, [
    {mcp, #{
        enabled => true,               %% défaut
        allowed_origins => any,        %% à restreindre pour les clients navigateur
        allow_missing_origin => true,
        resources => full,             %% full | live_only
        live => #{max_per_session => 32, max_global => 1024,
                  sweep_interval_ms => 60000, debounce_ms => 100,
                  orphan_ttl_ms => 600000},
        request_state_key => {file, "/etc/barrel/mcp-state.key"}
    }}
]}

Les requêtes live appartiennent à la session MCP qui les a créées ou, sur une connexion 2026-07-28 (sans sessions), au principal authentifié : max_per_session borne chaque propriétaire, et une requête appartenant à un principal est abandonnée après orphan_ttl_ms sans lecture (une requête appartenant à une session, quand sa session disparaît).

request_state_key (un binaire d’au moins 32 octets aléatoires, ou {file, Path} pour le lire dans un fichier au démarrage) scelle l’état des requêtes en plusieurs allers-retours. Chaque nœud d’une flotte doit porter la même clé : sinon, une nouvelle tentative qui arrive sur un autre nœud, ou sur le même nœud après un redémarrage, est refusée. Sur un nœud unique, laissez-la non définie : barrel_mcp utilise alors une clé éphémère et l’indique au démarrage.

Authentification

/mcp s’authentifie par son propre fournisseur, qui accepte deux bearers :

  • un jeton serveur (le même ensemble {barrel_server, auth, #{tokens => [...]}} que vérifie le middleware REST) : accès complet ;
  • un jeton de capacité (bsp_..., émis par barrel_caps) : limité à son espace et à ses droits ; chaque outil vérifie la base qu’il touche par rapport à l’autorisation. Les refus reviennent comme des erreurs d’outil que l’agent peut lire, pas comme des échecs de protocole.

Sans authentification configurée, le point d’accès est ouvert, comme le reste du serveur.

Outils

Cœur (entre parenthèses, les droits dont une capacité a besoin) :

db_create (write)      db_list (read)          db_info (read)
doc_get (read)         doc_put (write)         doc_delete (write)
query (read)           search (read)           ngram_search (read)
changes (read)         branch_create (admin)  branch_list (read)      merge (admin)
query_subscribe (write)                        query_unsubscribe

Couche agents :

space_create (management only)   space_info (read)
space_grant (admin)              space_revoke (admin)
session_create (write)           session_touch (write)
session_add_message (write)      session_get_messages (read)
handoff_create (admin)           handoff_list (read)
handoff_accept (token in args)   handoff_complete (token in args)

Contextes (voir contextes pour un pas-à-pas) :

OutilArguments requisRenvoie
context_capabilitiesaucunles formes d’instructions acceptées avec des exemples, les fusions, les limites, les budgets des ensembles de travail, l’état hors ligne
context_listaucun (prefix, unlisted){contexts: [card]}
context_discoverq{contexts, summary} : les fiches où chaque mot de q correspond
context_inspectcontext (nom ou id)une fiche
context_queryquery, et contexts ou working_setrows ou groups, sources, coverage, execution, summary
context_attachcontext (working_set, mode, credential_ref)l’ensemble de travail (un nouveau sans working_set)
context_detachworking_set, contextl’ensemble de travail
context_materializefrom_query (query, contexts)les tranches enregistrées, l’utilisation et le budget
context_importdir (working_set, name)l’ensemble de travail avec le membre importé
context_working_setsaucun (working_set pour en lire un)les ensembles de travail, ou un seul en entier
context_working_set_deleteworking_set{ok: true, deleted}
context_offlineaucun (offline pour basculer){offline: bool}

context_query prend aussi merge, offline, params, deadline_ms (5000 par défaut, au plus 60000), per_context_timeout_ms et max_parallel.

Un jeton de capacité peut utiliser context_capabilities, context_list, context_discover, context_inspect, context_query (chaque contexte local est vérifié comme une lecture sur sa base) et lire le mode hors ligne. Les ensembles de travail, les imports et le passage hors ligne demandent un jeton serveur.

Les outils de contexte signalent les échecs sous une seule forme, la même que les routes REST :

{"error": "unknown_context",
 "message": "No context has the id or name otp/sasll.",
 "hint": "Did you mean: otp/sasl? context_list (GET /contexts) shows every context.",
 "details": {"context": "otp/sasll", "suggestions": ["..."]}}

Un context_query auquel aucun contexte n’a répondu (execution: failed) revient comme un résultat d’erreur d’outil (isError: true) qui porte la réponse complète : vous pouvez ainsi lire l’error de chaque source.

query compile d’abord l’instruction (les erreurs d’analyse sont lisibles), borne les lignes avec max_rows (100 par défaut, plafond 1000) et pagine avec une continuation. Les instructions SUBSCRIBE sont rejetées et renvoyées vers query_subscribe. Chaque écriture porte une provenance : acteur = sujet authentifié, session = session MCP (ou l’argument session de l’outil), source = mcp. Voir audit-provenance.

Ressources et requêtes live

Trois modèles :

barrel://db/{db}              database info
barrel://db/{db}/doc/{id}     a document body
barrel://db/{db}/live/{sub}   the materialized snapshot of a live query

query_subscribe démarre une requête live et renvoie l’URI de sa ressource. Lisez l’URI pour obtenir les lignes courantes (#{ready, count, rows}, triées par id) ; abonnez-vous à elle (resources/subscribe) pour recevoir un notifications/resources/updated à chaque changement, temporisé, livré par le flux SSE GET du client. Le client relit à chaque notification.

{ok, C} = barrel_mcp_client:start(#{
    transport => {http, <<"http://localhost:8080/mcp">>},
    auth => {bearer, Token}}),
{ok, R} = barrel_mcp_client:call_tool(C, <<"query_subscribe">>, #{
    <<"db">> => <<"mydb">>,
    <<"query">> => <<"SELECT * FROM db WHERE kind = 'task' SUBSCRIBE">>}),
%% le contenu de R porte {"sub": SubId, "uri": Uri}
{ok, _} = barrel_mcp_client:subscribe(C, Uri),
receive {mcp_resource_updated, Uri, _} -> refetch end,
{ok, Snapshot} = barrel_mcp_client:read_resource(C, Uri).

Notes

  • Dans le framework MCP, les lectures de ressources ne portent aucun contexte d’authentification (handlers d’arité 1) : les modèles db et doc répondent donc à tout appelant authentifié. Définissez resources => live_only quand vous distribuez des jetons de capacité : les URI live contiennent 16 octets aléatoires, leur possession vaut capacité.
  • Le pont live possède chaque abonnement : les bases ayant des requêtes live actives sont maintenues ouvertes, les abonnements orphelins (dont la session MCP a expiré) sont balayés, et des plafonds par session et globaux bornent les agents qui s’emballent.
  • Les lignes d’un instantané live sont triées par id ; ORDER BY n’est pas maintenu d’un delta à l’autre.
  • Pour un principal à capacité, la base touchée par un outil doit être l’espace autorisé lui-même ; les bases de branche d’un espace ne sont pas accessibles avec une capacité en v1.
  • ngram_search prend db et query, avec mode (literal, le défaut, ou regex) et limit ; chaque résultat porte l’id du document et les plages de correspondance.
  • Aucun point d’entrée stdio (pour les hôtes MCP locaux) n’est câblé ; le moteur le permet si vous en avez besoin.

Traduit de la page anglaise: /docs/guides/mcp/ (docs/guides/mcp.md) Modifier cette page Voir en Markdown

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