---
name: minimal-core
description: Read and change data through Minimal Core, the data access layer over a database you already run. Use when a task names a Minimal deployment, an LB-Access-Token, the Auto API path /minimal/api/rest/auto/v1, or the MCP endpoint /minimal/mcp/rpc/v1.
---

# Minimal Core

Minimal Core serves every table of a registered database two ways: REST (Auto API) and MCP tools. Both pass the same permission checks, so a call refused on one is refused on the other.
Full reference: the Book of Minimal, https://littlebitlabs.com/docs (three volumes). Minimal Core is in beta.

## Before any call

- Send an access token in the `LB-Access-Token` header. It carries organization, project, space, user and roles. Never pass those as arguments.
- A token never holds more than the identity that minted it. `key_type` reads in create-read-update-delete order: `crud` is everything, `-r--` is read-only.
- MCP needs a token owned by an MCP identity, with MCP switched on for its space.

## REST: addressing a table

```
/minimal/api/rest/auto/v1/{org}/{project}/{type}/{schema}/{table}
```

- `type` is the two-letter database code: `pg`, `ms`, `ma`, `ch`.
- `org` and `project` are the lower-cased abbreviations the identity resolves to. A mismatch is refused with 400.
- `GET` reads, `POST` inserts, `PUT` updates, `DELETE` deletes.

## Reading rows

- `fc` picks columns, `oy` orders (`oy=id.as`), `ps` is page size, `pg` is page number. `ps` and `pg` are required.
- Filters are `column=operator.value`: `department_id=gt.6`, `full_name=like.Raf*`, `id=eq.5`.
- There is no default order. Always send `oy`, or the row order can change between calls.
- `format` is `json` (default), `xml`, `csv`, `yaml` or `bson`.
- Page modestly and read on until a page comes back empty.

## Writing rows

- Insert, update and delete are separate routes on the same path as the read. Bodies are in Vol. I, Chapter 5.
- `DELETE` ignores `ps` and `pg` and runs against every matching row. There is no recovery. Send a filter such as `id=eq.5`, and read the same filter with `GET` first.

## MCP

Endpoint: `POST /minimal/mcp/rpc/v1`, on its own port. Headers: `LB-Access-Token`, `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method: tools/call`, `Mcp-Name: <tool name>`.

Run these in order:

1. `server/discover` once. It returns `supportedVersions` and the server's instructions.
2. `start_ai_session` with `name` and `context` (both required). Keep `session_id` from the result and send it as `X-Session-Id` on every later call. Only `start_ai_session` and `help` work without it.
3. `meta_list_databases` returns `[{type, schema}]`. `meta_list_tables` takes that pair. `meta_describe_table` returns a table's columns.
4. `auto_read_rows`, `auto_insert_rows`, `auto_update_rows`, `auto_delete_rows`. Arguments: `type`, `schema`, `table`, and for reads `page_size`, `page_number` and `query` (for example `{"oy": "id.as"}`).

Notes:

- A tool's answer arrives as a JSON string inside `result.content[0].text`. Parse it.
- `auto_insert_rows` takes `rows` as an array, one object per row. A not-null column the database fills itself (an `id`) is sent as `null`.
- `help` with `{"tool": "<name>"}` returns one tool's full entry. `tools/list` lists all 115.
- Custom API definitions are called through one tool, `call_api`, with a definition's `uri`, `method` and `version`.
- `ping` checks the credential before a real call.

## Refusals

- REST refuses with 403 and a message that names the roles the caller held: `insufficient permissions for this operation on this table, got [hr-analyst]`. Three gates run in order: lock mask, permission template, row scope.
- A table hidden from the caller and a table that does not exist look the same.
- MCP says no in three shapes: a refusal at the credential layer, a JSON-RPC error for a tool name that does not exist, and a normal result with `isError: true`. Treat `isError: true` as a failure. Reporting it as success reports a write that never happened.

## Rules for the agent

- When refused, report the refusal and the roles it names. Do not retry with other credentials or look for a wider token.
- Never put a secret in a tool argument. Arguments are recorded into the session before the tool runs.