# Quickstart: server

[`barrel_server`](/docs/concepts/glossary#barrel-server) serves Barrel
over HTTP: a REST/JSON API for applications and an
[MCP](/docs/concepts/glossary#mcp) endpoint for agents. In this
quickstart you build it from source, start it, create a database, write
and read documents with `curl`, run a query, then reach the same data as
an agent would, through MCP tool calls. Use this path when your clients
are not written in Erlang, run on other machines, or are agents: anything
that speaks HTTP can use the database, and you run it as one service.

<Goal items={["Build and start barrel_server", "Create a database and write documents over REST", "See how a stale write is refused", "Run a BQL query over HTTP", "Call the database as MCP tools"]} />

## Before you start

- Erlang/OTP 26 or later, rebar3, CMake and a C/C++ compiler, to build
  the server and its native parts.
- git, to clone the source.
- `curl`, to send requests.

> **No build: use the image:** With Docker you can skip steps 1 and 2. Start the image, then continue at
> step 3:
> 
> ```shell
> docker run -p 8080:8080 ghcr.io/barrel-db/barrel-server:2026.11.9
> ```
> 
> Without `BARREL_AUTH_TOKENS` it logs `barrel: no BARREL_AUTH_TOKENS set,
> the server accepts every request` (run of the 2026.11.9 image), like the
> build below. See [Run barrel in Docker](/docs/guides/docker).

## 1. Build

The server lives in the Barrel umbrella repository, behind the `server`
build profile, so you clone it and compile with that profile.

```shell
git clone https://github.com/barrel-db/barrel.git
cd barrel
rebar3 as server compile
```

## 2. Configure and start

The server reads its settings from a `sys.config` file. You need two: the
port to listen on and the directory where databases are stored. Write it
at the root of the clone:

sys.config:

```erlang
[{barrel_server, [{http_port, 8080},
                  {data_dir, "/var/tmp/barrel/data"}]},
 {kernel, [{logger_level, notice}]}].
```

Start the server:

```shell
erl -noshell -config sys \
    -pa _build/server/lib/*/ebin \
    -eval 'application:ensure_all_started(barrel_server).'
```

For an interactive shell instead, run `rebar3 as server shell`, then
`application:ensure_all_started(barrel_server).`

Check that it answers:

```shell
curl localhost:8080/health
```

Output from a run on barrel_server 1.13.0:

```
{"status":"ok"}
```

> **Note:** The server is up and listening on port 8080. `/health` only tells you the
> HTTP listener answers; it does not check the databases. `GET /ready`
> answers `{"status":"ready"}` once the database and replication processes
> run.

> **Limit:** This server has no authentication: anyone who can reach the port can
> read and write. Lock it before you expose it. See
> [Authentication](/docs/security/authentication).

## 3. Create a database

A database is the unit you write to, query and replicate. Every route
that works on data starts with `/db/:db`, the database name.

```shell
curl -X PUT localhost:8080/db/demo
```

Output from a run on barrel_server 1.13.0:

```
HTTP/1.1 201 Created
{"ok":true,"db":"demo"}
```

> **Note:** `201 Created` means the database `demo` did not exist and now does.

Names use lowercase letters, digits, `_` and `-`, up to 63 bytes, and
must not start with `_`; any other name answers 400 `invalid_name`. Only
`PUT /db/:db` creates a database: every other `/db/:db/...` route answers
404 `{"error":"db_not_found"}` for a database that does not exist.

## 4. Write and read a document

A document is a JSON object stored under an id. `PUT` writes it at the id
in the URL (`a` here), `GET` reads it back.

```shell
curl -X PUT localhost:8080/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"hello world","kind":"note","n":1}'
curl localhost:8080/db/demo/doc/a
```

Output from a run on barrel_server 1.13.0:

```
{"id":"a","ok":true,
 "rev":"000001a1b876972d00000000@w78160d59891ba7d7"}
{"_rev":"000001a1b876972d00000000@w78160d59891ba7d7",
 "id":"a","kind":"note","n":1,"title":"hello world"}
```

> **Note:** The write answers with `rev`, the [revision](/docs/concepts/glossary#revision)
> token of the version it created. The read returns your fields plus that
> same token as `_rev`. It is how the server knows which version a later
> write was based on.

To update it, send the current `_rev` in the body. If someone else
updated the document since you read it, your `_rev` is stale and the
server refuses the write instead of losing their change. Try it with a
made-up `_rev`:

```shell
curl -X PUT localhost:8080/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"stale","_rev":"bogus"}'
```

Output from a run on barrel_server 1.13.0:

```
HTTP/1.1 409 Conflict
{"error":"conflict"}
```

> **Note:** `409 Conflict` means the document was not changed. Read it again to get
> the current `_rev`, apply your edit, and send it back.

Write several at once with `_bulk_docs`:

```shell
curl -X POST localhost:8080/db/demo/_bulk_docs \
  -H 'content-type: application/json' \
  -d '{"docs":[{"id":"c","kind":"note","title":"third"},
              {"id":"d","kind":"note","title":"fourth"}]}'
```

## 5. Query with BQL

[BQL](/docs/concepts/glossary#bql) is Barrel's query language, close to
SQL, and every field is indexed, so you can filter on any field.
`POST /db/:db/query` takes the query as the body and answers newline-delimited JSON: one line per row,
then a `meta` line.

```shell
curl -X POST localhost:8080/db/demo/query \
  -H 'content-type: text/plain' \
  --data-binary "SELECT id, title FROM c
    WHERE kind = 'note' ORDER BY id LIMIT 2"
```

Output from a run on barrel_server 1.13.0:

```
{"row":{"id":"a","title":"hello world"}}
{"row":{"id":"c","title":"third"}}
{"meta":{"count":2,"bound":"limit_reached",
 "last_seq":"AAABobpEb-MAAAAB",
 "instance_id":"4552d48d297c5b2b","has_more":false}}
```

> **Note:** Each `row` line is one matching document, with the fields you selected.
> The `meta` line says how the answer ended: `count` rows, `bound` is
> `limit_reached` because `LIMIT 2` stopped it, and `has_more` is false so
> there is no next page. `instance_id` and `last_seq` name the database
> copy and the point in its change history the answer reflects.

Send JSON instead (`{"query": ..., "params": ...}`) when you pass
parameters or `max_rows`.

The collection name after `FROM` is ignored: the database comes from the
URL. See [Query with BQL](/docs/guides/query-bql).

## 6. Call it over MCP

MCP (Model Context Protocol) is the protocol agent runtimes use to call
tools. The same server answers MCP at `/mcp` (Streamable HTTP), so an
agent works on the same databases as your REST clients. Here you play the
agent with `curl`. First initialize a session and keep the
`mcp-session-id` header it returns:

```shell
curl -i -X POST localhost:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"0"}}}'
```

Output from a run of the Barrel 2026.11.9 image (barrel_server 1.15.1):

```
HTTP/1.1 200 OK
content-type: application/json
mcp-session-id: mcp_23d2e1810ba8c2aaa733edf74b6814cf
{"id":1,"jsonrpc":"2.0","result":{"capabilities":{...},
 "protocolVersion":"2025-06-18",
 "serverInfo":{"name":"barrel","version":"4.5.1"}}}
```

> **Note:** The server agreed on protocol version `2025-06-18` and opened an MCP
> session. The `mcp-session-id` header identifies that session; send it with
> every following request.

Send `notifications/initialized`, then call a tool. Every request after
`initialize` carries the session id and the protocol version:

```shell
SID=mcp_23d2e1810ba8c2aaa733edf74b6814cf
mcp() {
  curl -s -X POST localhost:8080/mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -H "mcp-session-id: $SID" \
    -H 'mcp-protocol-version: 2025-06-18' -d "$1"
}
mcp '{"jsonrpc":"2.0","method":"notifications/initialized"}'
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call",
      "params":{"name":"db_create",
                "arguments":{"db":"mcpdemo"}}}'
mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call",
      "params":{"name":"doc_put","arguments":{"db":"mcpdemo",
        "doc":{"id":"note-1","title":"stored over MCP"}}}}'
mcp '{"jsonrpc":"2.0","id":4,"method":"tools/call",
      "params":{"name":"query","arguments":{"db":"mcpdemo",
        "query":"SELECT id, title FROM c LIMIT 5"}}}'
```

Tool calls answer as server-sent events. The tool result is JSON in the
`text` field:

Output from a run on barrel_server 1.13.0:

```
data: {"id":2,"jsonrpc":"2.0","result":{"content":[{"text":
  "{\"ok\":true,\"db\":\"mcpdemo\"}","type":"text"}]}}

data: {"id":3,"jsonrpc":"2.0","result":{"content":[{"text":
  "{\"id\":\"note-1\",\"ok\":true,\"rev\":
  \"000001a1ba44713d00000000@w1b9de1b98c6d4949\"}",
  "type":"text"}]}}

data: {"id":4,"jsonrpc":"2.0","result":{"content":[{"text":
  "{\"count\":1,\"rows\":[{\"id\":\"note-1\",
  \"title\":\"stored over MCP\"}],\"has_more\":false}",
  "type":"text"}]}}
```

> **Note:** Each `data:` line answers the request with the same `id`. Request 2
> created the database `mcpdemo`, request 3 wrote `note-1` and got its
> `rev`, and request 4 ran a BQL query that found it. These are the same
> operations as the REST calls above, named as tools.

`tools/list` returns 39 tools. See [MCP endpoint](/docs/guides/mcp) to
point an agent at it.

## Notes

- Vector stores go next to the documents under `data_dir`, as
  `<data_dir>/<name>.vectordb`. A store created before barrel 1.13.0 in
  `./priv/` under the directory you started the server from keeps being
  used there.
- Default databases have a 768-dimension vector store, no embedder and
  BM25 off, so `/search/bm25` and `/search/hybrid` answer 500 until you
  configure them. See [Run the server](/docs/guides/rest-server).
- `/health` returns ok without checking anything. Point a load balancer
  or orchestrator at `/ready` instead: it answers 503
  `{"status":"not_ready","failed":[...]}` when a database or replication
  process is down.

<NextSteps steps={[
  { href: '/docs/security/authentication', label: 'Authentication', why: 'Lock the server before anyone else can reach its port.' },
  { href: '/docs/guides/rest-server', label: 'Run the server', why: 'See every route, query bounds, CORS and authentication settings.' },
  { href: '/docs/guides/mcp', label: 'MCP endpoint', why: 'Point an agent runtime at the server.' },
  { href: '/docs/start/quickstart-browser', label: 'Quickstart: browser', why: 'Keep a copy of a database in a web app and sync it with this server.' },
]} />
