API Reference barrel_server v#1.0.1

Application entry point for the barrel server.

Bearer-token auth for the whole REST API.

Per-route capability authorization for the agent-layer REST surface. The auth middleware only authenticates; each handler asks this module whether the presented bearer covers the space and right it is about to touch.

CORS for the REST API, in front of auth.

Server-side database access: a thin, stateless shim over Barrel's database lifecycle manager (barrel_dbs), which owns the open handles, touches them on use, closes idle ones, and bounds the open set. This module adds only the HTTP concerns: name validation and the server-wide open options from the app env.

REST/JSON HTTP surface for the barrel edge database.

The MCP endpoint: mounts livery_mcp (the Streamable HTTP bridge to the barrel_mcp engine) at /mcp inside the REST router. Configured with {barrel_server, mcp, #{...}}

The agent-layer MCP tools: spaces, capability grants, sessions, and handoffs, calling barrel_spaces / barrel_caps / barrel_session / barrel_handoff directly. Authorization mirrors the REST surface: space creation is management-only (global principals), grant administration needs admin on the space, session reads/writes follow the right ladder, and handoff accept/complete need nothing but the handoff token: possession is the right.

barrel_mcp_auth provider for the /mcp endpoint, and the authorization helpers the MCP tools consume.

The live-query bridge: owns every barrel:subscribe_query subscription created over MCP. The bridge process is the subscription owner, so a bridge crash tears all live queries down cleanly; databases with active subscriptions are pinned in the lifecycle manager so the idle sweeper cannot close them mid-query.

The MCP resource templates: barrel://db/{db} (database info), barrel://db/{db}/doc/{id} (a document body), and barrel://db/{db}/live/{sub} (the materialized snapshot of a live query, see barrel_server_mcp_live).

The core MCP tools: databases, documents, BQL, search, the changes feed, and the timeline (branch/merge). Every handler is arity 2; the Ctx carries the authenticated principal, which barrel_server_mcp_auth:allow/3 checks against the database and right each tool touches. Denials come back as isError tool results, not protocol errors: agents recover better from content they can read.

Agent-layer REST surface: spaces, capability grants, sessions, and handoffs over HTTP. Space and handoff creation are management operations (global bearer only); everything scoped to one space accepts a capability token checked per method through barrel_server_caps (GETs need read, mutations write, grant administration admin).

Top supervisor for the barrel server.

Replication endpoints: the barrel_rep_transport callbacks as HTTP, under /db/:db/_sync/*.