MCP Server
In the admin: Settings › Data API › MCP
Turning it on
In Settings › Data API › MCP, turn on Enable MCP. It's off by default; while off, /mcp answers RESOURCE_NOT_FOUND and totalbase-mcp refuses to start. The page shows the address, a link to create a token, and the commands below for your instance.
Connecting
The endpoint is POST /mcp at the instance's address. It's stateless: each request carries the token.
Claude Code:
claude mcp add --transport http totalbase https://ops.acme-field.example/mcp \
--header "Authorization: Bearer $TOTALBASE_TOKEN"
A project's .mcp.json:
{
"mcpServers": {
"totalbase": {
"type": "http",
"url": "https://ops.acme-field.example/mcp",
"headers": { "Authorization": "Bearer ${TOTALBASE_TOKEN}" }
}
}
}
Over stdio, for clients that only start a local process:
TOTALBASE_URL=https://ops.acme-field.example TOTALBASE_TOKEN=tb_... totalbase-mcp
totalbase-mcp isn't published as a package yet: run it from a checkout of the repository (pnpm install && pnpm -r run build, then node packages/mcp-server/dist/cli.js). Most MCP clients speak HTTP, which needs nothing installed.
The token must be an Admin API token of a user who holds the Administrators role. See AI Agents › Tokens.
Modes
| Mode | The agent gets |
|---|---|
| Read only | only the tools that read: describe tables, list roles, query records, preview a dashboard query |
| Standard | every tool except delete_* and revoke_*. Inside the tools that remain, a delete of records, a column or table drop in alter_table, and SQL that destroys data or access are refused |
| Full (the default) | everything; destructive calls need confirm=true |
The mode only narrows: TotalBase's permissions still decide every call. The agent is told its mode and which groups are off when it connects.
apply_dashboard (which replaces a dashboard draft's widgets, with a dry_run option) stays available in Standard, and revoke_permission needs no confirm in Full.Destructive calls
In Full mode, tools that delete or drop take a confirm argument: without confirm=true they refuse and say what would happen. The orientation tells the agent to ask you first. alter_table also takes preview=true, to show its SQL without running it.
Project instructions
Project instructions (up to 8000 characters) are given to every agent after TotalBase's own orientation, as this project's own instructions, from its administrators. Write your conventions there:
- Table and column names in English, snake_case, plural tables.
- Every table gets created_at and updated_at.
- Never touch the invoices or invoice_items tables: Accounting owns them.
- UI labels in Spanish (Argentina).
- Ask before publishing anything to the Technician role.
Limits and protection
| Setting | |
|---|---|
| Requests per minute | 120 per token by default; past it, RATE_LIMIT_EXCEEDED |
| Allowed hosts | the host names /mcp answers to; empty, the public URL's host and localhost. Another host gets PERMISSION_DENIED, which protects against DNS rebinding |
A tool called with an argument it doesn't take is refused, naming the arguments it does take.
Guides
The server offers guides as MCP resources, totalbase://guide/<name>: build, modeling, permissions, data-api, totalbase-tables, files, dataviews, pages, widgets, dashboards, pdf-templates, workflows, errors. Some are generated live from your instance, such as the TotalBase tables it exposes and the workflow steps it supports.
Errors
| Error | When |
|---|---|
RESOURCE_NOT_FOUND on /mcp | MCP is off |
PERMISSION_DENIED | the token's user isn't an administrator, or the host isn't allowed |
RATE_LIMIT_EXCEEDED | too many requests per minute |
SQL_CONSOLE_DISABLED | SQL tools without Allow API tokens |
| a mode refusal | not allowed: this instance runs MCP in STANDARD mode |