AI agents and scripts
BetterMyAdmin has a small JSON API and an MCP endpoint for
programs that do not need the web interface: AI agents (Claude Code, Claude Desktop, Cursor, …),
scripts and CI jobs. Both are off until $cfg['AgentApi'] is set to true.
Every request carries its own credentials; there is no session and no CSRF token. A request
authenticates as a MySQL user, as people do when they log in, and that user’s privileges decide
what it can see and change. The login rules apply as for a login:
$cfg['Servers'][$i]['AllowDeny']['rules'],
$cfg['Servers'][$i]['AllowRoot'],
$cfg['Servers'][$i]['AllowNoPassword'] and the failed-login limiter.
How a request authenticates depends on the server’s
$cfg['Servers'][$i]['auth_type']:
cookie,httpHTTP Basic with the MySQL user and password (
Authorization: Basic …). A request without them gets401withWWW-Authenticate: Basic.configThe configured user; the request needs no credentials. Protect such a server’s address as you would its web interface.
signonThe
$cfg['Servers'][$i]['SignonPage']module’sagentCredentialsexport, which reads the credentials from the request (for example a single sign-on proxy’s header) and returns{user, password}, ornullwhen the request has none.
Requests from a web page of another site are refused (an Origin header of another host), and a
POST must be Content-Type: application/json: browsers send HTTP Basic credentials and a
sign-on proxy’s cookie on their own, so this keeps other sites from using them.
The API
All paths are below /api/agent/v1/servers/<n>, where <n> is the server’s number (1 for
the first). Answers are JSON; errors are {"error": {"code": …, "message": …}} with an HTTP
status (a MySQL error adds errno and sqlstate).
GET /databases{"databases": [...]}: the databases the user may see, after$cfg['Servers'][$i]['only_db']and$cfg['Servers'][$i]['hide_db'].GET /databases/<db>/tables{"tables": [{"name", "type": "table"|"view", "engine", "rows", "comment"}]}.rowsis the storage engine’s estimate.GET /databases/<db>/tables/<table>The columns (name, type, nullable, key, default, extra, collation, comment), the indexes and the
CREATE TABLEstatement.POST /query{"sql": "...", "db": "...", "maxRows": 100}Runs the SQL like the SQL box: statements split on
;,dbas the default database, aSELECTwithoutLIMITlimited tomaxRowsrows (default$cfg['MaxRows'], at most 10000;truncatedsays when there were more), andDROP DATABASErefused unless$cfg['AllowUserDropDatabase']. Execution stops at the first failing statement. Each statement comes back withcolumnsandrows, oraffectedRows/insertId, or itserror. Values are strings exactly as the server sent them (DECIMALandBIGINTkeep every digit),NULLisnull, and binary values are{"base64": "..."}.POST /explain{"sql": "...", "db": "..."}The server’s
EXPLAINof one statement, in the same form.
For example:
curl -u 'reporter:secret' -H 'Content-Type: application/json' \
-d '{"sql": "SELECT COUNT(*) FROM orders", "db": "shop"}' \
https://bma.example.com/api/agent/v1/servers/1/query
MCP
POST /api/agent/v1/servers/<n>/mcp is an MCP server (Streamable HTTP transport, JSON
responses, no session). Its tools are list_databases, list_tables, describe_table,
query and explain, with the API’s answers as their results. For Claude Code, add it to the
project’s .mcp.json:
{
"mcpServers": {
"bettermyadmin": {
"type": "http",
"url": "https://bma.example.com/api/agent/v1/servers/1/mcp",
"headers": { "Authorization": "Basic cmVwb3J0ZXI6c2VjcmV0" }
}
}
}
Behind Cloudflare Access (the signon setup of the phpmyadmin-sso image), the headers are a
service token’s instead: "CF-Access-Client-Id" and "CF-Access-Client-Secret". The token
signs on as its own MySQL user (svc-…), created without privileges: grant it what the agent
may do.