AI Agents

Overview

What an AI agent can administer, and how you keep control.

TotalBase is built to be administered by AI agents. Its MCP server gives an agent, such as Claude Code, the same operations you have in the admin: create tables and constraints, set permissions, build DataViews and dashboards, write workflows and templates, load records. Quickstart with AI shows a whole application built from one prompt; this section is the reference behind it.

How it works

agent ──MCP──▶ /mcp ──▶ Admin API and Data API, in the same process
                         as the token's user, with the user's permissions

The MCP server isn't a second way in. Each tool call becomes an ordinary request to the Admin API or the Data API, with the agent's token: the same validation, permissions, guardrails and audit as a person in the admin. What PostgreSQL refuses, it refuses for the agent too.

Two ways to connect:


`/mcp` on the instance	over HTTP, with a token. For any MCP client, local or remote
`totalbase-mcp`	a command that speaks MCP over stdio, for clients that start a local process. It takes `TOTALBASE_URL` and `TOTALBASE_TOKEN` and applies the same policy

See MCP Server.

What the agent knows

How to work: on connecting it receives an orientation and a set of guides (build order, modeling, permissions, the query language, DataViews, pages, dashboards, workflows, PDF templates, errors), generated from the code so they match what the server accepts.
What exists: tools that describe your tables, roles, screens and settings before it changes anything.
What went wrong: stable error codes, such as CHECK_VIOLATION with your constraint's message.
Your conventions: the project instructions you write in Settings › MCP.

Keeping control

Four layers, each narrowing the one before:

The mode: Read only, Standard or Full.
The tool groups switched on.
The token's user: an agent can do what that user can, and nothing more.
Confirmation: destructive calls in Full mode need an explicit confirm, which the agent is told to ask you for.

And around them: the agent builds drafts that reach users only when published; every action is in Logs, marked TotalBase MCP; raw SQL is off unless you turn it on; and MCP settings can't be changed with a token, so an agent can't widen its own limits. Revoke the token or turn MCP off to stop it.

Give the agent its own administrator user instead of your token: its actions then show apart from yours in Logs. See AI Agents › Tokens.

Without MCP: the Admin API

Everything the MCP server does goes through the Admin API, and an agent or a program can call it directly. It describes itself in an OpenAPI 3.1 document, GET /admin/api/openapi, which tools that import OpenAPI turn into actions: ChatGPT's Actions, n8n, LangChain's OpenAPI toolkit. A script or a CI pipeline uses it the same way, to create tables, grant permissions or publish a DataView as code.

	MCP server	Admin API directly
For	agents that speak MCP: Claude Code, Claude Desktop, Cursor…	any HTTP client, OpenAPI-based agents, scripts, CI
Guides and orientation	given to the agent on connecting	none: the OpenAPI document describes each route
Mode and tool groups	applied	not applied
Confirmation of destructive calls	required in Full mode	none: a `DELETE` deletes
Permissions, guardrails, PostgreSQL constraints, audit	applied	applied

The MCP mode and tool groups only limit /mcp. A token with Admin API access can do anything its administrator can, whatever Settings › MCP says. Give a direct-API agent or script the narrowest user and token you can, and revoke it when it's done.

Next steps

Recipes: what to ask, and the calls the agent makes.
MCP Server.
Tools.

Activity

What you did through TotalBase, from the audit log.

Tokens

The token an agent uses, its own user, expiry and SQL access.