Barrel
FR GitHub

An MCP session with curl

This script talks to barrel_server's MCP endpoint the way an agent does, one JSON-RPC message at a time: it initializes a session, lists the tools, creates a database, writes and reads documents, runs a BQL query and a substring search, and ends the session. It prints every request and the tool result it got back. Use it to see the wire format before you connect an MCP client, or to test a server you deployed.

Prerequisites

  • A running barrel_server (1.13 or later). From a checkout of the barrel repository:

    rebar3 as server compile
    rebar3 as server shell

    The shell starts barrel_server on port 8080, with no auth.

  • curl and jq.

Run

BARREL_URL=http://localhost:8080 ./run.sh

On a server with bearer auth, also set BARREL_TOKEN. The script deletes and recreates the database mcp_demo (over REST) so every run starts empty.

What it shows

  • POST /mcp with initialize returns the session id in the mcp-session-id response header; every later request sends it back, with mcp-protocol-version: 2025-06-18.
  • initialize and tools/list answer plain JSON; tools/call answers as server-sent events (data: {...}). The script keeps the JSON.
  • A tool result is a JSON document in the text content. A failed call is still a result, with isError: true, for example {"error":"not_found"}.
  • DELETE /mcp ends the session (204).

Notes

  • ngram_search finds exact substrings with no extra setup. search in bm25 or hybrid mode needs BM25 or an embedder configured on the database; on a default server it returns an error result.
  • /mcp accepts bearer tokens only (a server token or a capability token), not signed requests or mTLS.

Expected output

The requests and the results, in order. The output of a real run is in expected.txt; the session id and revisions differ on every run.

Download The folder on GitHub, with every file below.

Source

run.sh
#!/bin/sh
# One MCP session against a running barrel_server, with curl.
#   BARREL_URL (default http://localhost:8080)
#   BARREL_TOKEN (optional bearer, for a server with auth)
# Needs curl and jq.
set -eu
URL="${BARREL_URL:-http://localhost:8080}"
DB=mcp_demo
HDRS=$(mktemp)
trap 'rm -f "$HDRS"' EXIT
AUTH=""
[ -n "${BARREL_TOKEN:-}" ] && AUTH="authorization: Bearer $BARREL_TOKEN"

# post <json>: POST one JSON-RPC message to /mcp, print the body.
# tools/call answers as SSE ("data: {...}"): keep the JSON.
post() {
  curl -sS -D "$HDRS" -X POST "$URL/mcp" \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -H 'mcp-protocol-version: 2025-06-18' \
    ${SID:+-H "mcp-session-id: $SID"} \
    ${AUTH:+-H "$AUTH"} \
    -d "$1" | awk '/^data: /{print substr($0, 7); next} /^\{/'
}

# call <id> <tool> <arguments>: print the request, then the tool
# result (a JSON document in the text content).
call() {
  req="{\"jsonrpc\":\"2.0\",\"id\":$1,\"method\":\"tools/call\","
  req="$req\"params\":{\"name\":\"$2\",\"arguments\":$3}}"
  echo "--> $req"
  post "$req" | jq '{isError: (.result.isError // false),
                     result: (.result.content[0].text | fromjson)}'
  echo
}

# Start from an empty database (REST, outside MCP).
curl -sS -o /dev/null -X DELETE ${AUTH:+-H "$AUTH"} \
  "$URL/db/$DB?purge=true" || true

INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
echo "--> $INIT"
SID=""
post "$INIT" | jq -c '.result | {protocolVersion, serverInfo}'
SID=$(tr -d '\r' < "$HDRS" | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}')
echo "mcp-session-id: $SID"
echo

echo '--> {"jsonrpc":"2.0","method":"notifications/initialized"}'
post '{"jsonrpc":"2.0","method":"notifications/initialized"}'
sed -n '1s/\r$//p' "$HDRS"
echo

echo '--> {"jsonrpc":"2.0","id":2,"method":"tools/list"}'
post '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | jq -r '"\(.result.tools | length) tools:",
           (.result.tools | map(.name) as $n
            | range(0; $n | length; 4) | $n[.:. + 4] | join(", "))'
echo

call 3 db_create "{\"db\":\"$DB\"}"
call 4 doc_put "{\"db\":\"$DB\",\"doc\":{\"id\":\"note-1\",\"title\":\"stored over MCP\",\"tags\":[\"mcp\"]}}"
call 5 doc_put "{\"db\":\"$DB\",\"doc\":{\"id\":\"note-2\",\"title\":\"release checklist\",\"tags\":[\"ops\"]}}"
call 6 doc_get "{\"db\":\"$DB\",\"id\":\"note-1\"}"
call 7 query "{\"db\":\"$DB\",\"query\":\"SELECT id, title FROM c WHERE 'ops' IN tags LIMIT 5\"}"
call 8 ngram_search "{\"db\":\"$DB\",\"query\":\"over MCP\"}"
call 9 doc_get "{\"db\":\"$DB\",\"id\":\"missing\"}"

echo "--> DELETE /mcp"
curl -sS -o /dev/null -w '%{http_code}\n' -X DELETE "$URL/mcp" \
  -H "mcp-session-id: $SID" ${AUTH:+-H "$AUTH"}

Expected output

The expected.txt of the example, from a real run. Revisions, ids, tokens and timestamps differ on every run; scripts/verify-examples.sh masks them before it compares.

expected.txt
--> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}
{"protocolVersion":"2025-06-18","serverInfo":{"name":"barrel","version":"4.5.1"}}
mcp-session-id: mcp_07e8b892aebc73ad4d6ae187860202d9

--> {"jsonrpc":"2.0","method":"notifications/initialized"}
HTTP/1.1 202 Accepted

--> {"jsonrpc":"2.0","id":2,"method":"tools/list"}
39 tools:
branch_create, branch_list, changes, context_attach
context_capabilities, context_detach, context_discover, context_import
context_inspect, context_list, context_materialize, context_offline
context_query, context_working_set_delete, context_working_sets, db_create
db_info, db_list, doc_delete, doc_get
doc_put, handoff_accept, handoff_complete, handoff_create
handoff_list, merge, ngram_search, query
query_subscribe, query_unsubscribe, search, session_add_message
session_create, session_get_messages, session_touch, space_create
space_grant, space_info, space_revoke

--> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"db_create","arguments":{"db":"mcp_demo"}}}
{
  "isError": false,
  "result": {
    "ok": true,
    "db": "mcp_demo"
  }
}

--> {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"doc_put","arguments":{"db":"mcp_demo","doc":{"id":"note-1","title":"stored over MCP","tags":["mcp"]}}}}
{
  "isError": false,
  "result": {
    "id": "note-1",
    "ok": true,
    "rev": "000001a1ba5581d600000000@w9c81a31430ff0acd"
  }
}

--> {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"doc_put","arguments":{"db":"mcp_demo","doc":{"id":"note-2","title":"release checklist","tags":["ops"]}}}}
{
  "isError": false,
  "result": {
    "id": "note-2",
    "ok": true,
    "rev": "000001a1ba55822000000000@w9c81a31430ff0acd"
  }
}

--> {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"doc_get","arguments":{"db":"mcp_demo","id":"note-1"}}}
{
  "isError": false,
  "result": {
    "_rev": "000001a1ba5581d600000000@w9c81a31430ff0acd",
    "id": "note-1",
    "tags": [
      "mcp"
    ],
    "title": "stored over MCP"
  }
}

--> {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"query","arguments":{"db":"mcp_demo","query":"SELECT id, title FROM c WHERE 'ops' IN tags LIMIT 5"}}}
{
  "isError": false,
  "result": {
    "count": 1,
    "rows": [
      {
        "id": "note-2",
        "title": "release checklist"
      }
    ],
    "has_more": false
  }
}

--> {"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"ngram_search","arguments":{"db":"mcp_demo","query":"over MCP"}}}
{
  "isError": false,
  "result": {
    "count": 1,
    "hits": [
      {
        "id": "note-1",
        "spans": [
          [
            7,
            8
          ]
        ]
      }
    ]
  }
}

--> {"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"doc_get","arguments":{"db":"mcp_demo","id":"missing"}}}
{
  "isError": true,
  "result": {
    "error": "not_found"
  }
}

--> DELETE /mcp
204

Up and down to moveEnter to open