Barrel
FR GitHub

MCP endpoint

barrel_server mounts an MCP endpoint (Streamable HTTP) at /mcp: tools for databases, documents, BQL, search, the timeline, the agent layer, and contexts, plus resources with live-query subscriptions. Read this when an MCP client (an agent runtime, an IDE, barrel_mcp_client) should talk to barrel directly.

When to use it

  • Agents reach barrel through an MCP runtime instead of REST.
  • You want live queries pushed to clients as resource-updated notifications.
  • You hand agents capability tokens scoped to one space and want the same scoping on the MCP surface.

Enable and configure

The endpoint is on by default in the server build. Configure it with the {barrel_server, mcp, #{...}} app env:

{barrel_server, [
    {mcp, #{
        enabled => true,               %% default
        allowed_origins => any,        %% tighten for browser clients
        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"}
    }}
]}

Live queries belong to the MCP session that created them, or, on a 2026-07-28 connection (no sessions), to the authenticated principal: max_per_session bounds each owner, and a principal-owned query is dropped after orphan_ttl_ms without a read (a session-owned one when its session goes).

request_state_key (a binary of 32 or more random bytes, or {file, Path} to read it from a file at start) seals the state of multi round-trip requests. Every node of a fleet must carry the same key: a retry that lands on another node, or on the same node after a restart, is refused otherwise. Leave it unset on a single node and barrel_mcp uses an ephemeral key, saying so at start.

Auth

/mcp authenticates through its own provider, which accepts two bearers:

  • a server token (the same {barrel_server, auth, #{tokens => [...]}} set the REST middleware checks): full access;
  • a capability token (bsp_..., issued by barrel_caps): scoped to its space and rights; every tool checks the database it touches against the grant. Denials come back as tool errors the agent can read, not protocol failures.

With no auth configured the endpoint is open, like the rest of the server.

Tools

Core (rights a capability needs in parens):

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

Agent layer:

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)

Contexts (see contexts for a walkthrough):

ToolRequired argumentsReturns
context_capabilitiesnoneaccepted statement shapes with examples, merges, limits, working-set budgets, offline state
context_listnone (prefix, unlisted){contexts: [card]}
context_discoverq{contexts, summary}: cards where every word of q matches
context_inspectcontext (name or id)one card
context_queryquery, and contexts or working_setrows or groups, sources, coverage, execution, summary
context_attachcontext (working_set, mode, credential_ref)the working set (a new one without working_set)
context_detachworking_set, contextthe working set
context_materializefrom_query (query, contexts)the slices saved, usage and budget
context_importdir (working_set, name)the working set with the imported member
context_working_setsnone (working_set to read one)the working sets, or one in full
context_working_set_deleteworking_set{ok: true, deleted}
context_offlinenone (offline to switch){offline: bool}

context_query also takes merge, offline, params, deadline_ms (default 5000, at most 60000), per_context_timeout_ms and max_parallel.

A capability token can use context_capabilities, context_list, context_discover, context_inspect, context_query (each local context is checked as a read on its database) and read the offline mode. Working sets, imports and switching offline need a server token.

Context tools answer failures in one shape, the same as the REST routes:

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

A context_query that no context answered (execution: failed) comes back as a tool error result (isError: true) carrying the full answer, so you can read each source's error.

query compiles the statement first (parse errors are readable), bounds rows with max_rows (default 100, cap 1000), and pages with a continuation. SUBSCRIBE statements are rejected toward query_subscribe. Every write carries provenance: actor = authenticated subject, session = MCP session (or the tool's session argument), source = mcp. See audit-provenance.

Resources and live queries

Three templates:

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 starts a live query and returns its resource URI. Read the URI for the current rows (#{ready, count, rows}, id-sorted); subscribe to it (resources/subscribe) to get a notifications/resources/updated on every change, debounced, delivered over the client's GET SSE stream. The client re-reads on 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">>}),
%% R's content carries {"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

  • Resource reads carry no auth context in the MCP framework (arity-1 handlers), so the db and doc templates answer any authenticated caller. Set resources => live_only when you hand out capability tokens: live URIs embed 16 random bytes, possession is the capability.
  • The live bridge owns every subscription: databases with active live queries are pinned open, orphaned subscriptions (their MCP session expired) are swept, and per-session/global caps bound runaway agents.
  • Rows of a live snapshot are id-sorted; ORDER BY is not maintained across deltas.
  • For a capability principal, the database a tool touches must be the granted space itself; branch databases of a space are not reachable with a capability in v1.
  • ngram_search takes db and query, with mode (literal, the default, or regex) and limit; each hit carries the document id and the match spans.
  • A stdio entry point (for local MCP hosts) is not wired; the engine supports it if you need one.

From docs/guides/mcp.md in the barrel repository at 794415d, updated 2026-09-26 Edit this page View as Markdown

Up and down to moveEnter to open