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 shellThe 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 /mcpwithinitializereturns the session id in themcp-session-idresponse header; every later request sends it back, withmcp-protocol-version: 2025-06-18.initializeandtools/listanswer plain JSON;tools/callanswers 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 /mcpends the session (204).
Notes
ngram_searchfinds exact substrings with no extra setup.searchinbm25orhybridmode needs BM25 or an embedder configured on the database; on a default server it returns an error result./mcpaccepts 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
#!/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.
--> {"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