Repository navigation
AI agents
Since 3.15.0 Databucket has a built-in MCP server (Model Context Protocol), so AI agents and assistants - Claude Code, Claude Desktop, Cursor, GitHub Copilot in VS Code and others - can work with your test data: find a test account that fits a scenario, reserve it for a test, change it, check its history, prepare new data.
The agent works as a Databucket user: with the user's role, in the project the user signed in to, and only in the buckets the user has access to. Everything it changes is recorded under that user's name in the data history, as with the API.
The MCP server is off by default. Switch it on in the configuration (see Installation):
databucket:
mcp:
enabled: trueor with the environment variable DATABUCKET_MCP_ENABLED=true. The server is then available at:
<databucket url>/mcp
It uses the Streamable HTTP transport and is stateless: every call stands on its own, so it works behind a load balancer and with several Databucket instances.
Create a dedicated user for the agent (see Manage users), assign it to the project and give it access to the buckets the agent should see. Choose its role:
- AGENT - reads, searches, inserts, modifies, reserves and releases data, reads the history; can't delete data or clear the history. The safe choice for an assistant that works next to people.
- ROBOT or higher - can also delete data.
See Roles & permissions. Like ROBOT, an AGENT user can't use the web application.
The agent sends the same token as any API client, in the header Authorization: Bearer <token>. Sign in with the agent's user and the project (see Get started with API):
curl -s -H "Content-Type: application/json" \
-d '{"username": "my-agent", "password": "secret", "projectId": 1}' \
<databucket url>/api/public/signinCopy the token from the response. With single sign-on and the password sign-in switched off, get the token with a client token from the provider instead (see Single sign-on → Robots).
The token is valid for jwt.expire.hours (24 in the example configuration) and is bound to one project. When it expires, the agent's calls are refused (401): get a new token and update the client configuration. To work with another project, sign in with its projectId.
Keep the token out of files you commit: the examples below read it from the environment variable DATABUCKET_TOKEN.
Claude Code
claude mcp add --transport http databucket <databucket url>/mcp \
--header "Authorization: Bearer $DATABUCKET_TOKEN"(in PowerShell: $env:DATABUCKET_TOKEN), or in the project's .mcp.json (the variable is read when Claude Code starts; when it isn't set, the text ${DATABUCKET_TOKEN} is sent and Databucket answers 401):
{
"mcpServers": {
"databucket": {
"type": "http",
"url": "<databucket url>/mcp",
"headers": { "Authorization": "Bearer ${DATABUCKET_TOKEN}" }
}
}
}Cursor - .cursor/mcp.json:
{
"mcpServers": {
"databucket": {
"url": "<databucket url>/mcp",
"headers": { "Authorization": "Bearer ${env:DATABUCKET_TOKEN}" }
}
}
}GitHub Copilot in VS Code - .mcp.json in the workspace root (or ~/.copilot/mcp-config.json for all workspaces):
{
"mcpServers": {
"databucket": {
"type": "http",
"url": "<databucket url>/mcp",
"headers": { "Authorization": "Bearer ${DATABUCKET_TOKEN}" }
}
}
}Claude Desktop and other clients that start local servers only - through the mcp-remote bridge (needs Node.js), in claude_desktop_config.json:
{
"mcpServers": {
"databucket": {
"command": "npx",
"args": ["-y", "mcp-remote", "<databucket url>/mcp", "--header", "Authorization:${AUTH_HEADER}"],
"env": { "AUTH_HEADER": "Bearer <token>" }
}
}
}Write Authorization:${AUTH_HEADER} without spaces, as above. For a Databucket address with http:// on another machine, add "--allow-http" to args - better use https://, as the token travels in the header.
The server tells the agent how to start and how to write rules; the agent picks the tools itself.
| Tool | What it does |
|---|---|
list_buckets |
The buckets the user has access to: name, description, class, history, protected data |
describe_bucket |
The fields of the bucket's class (title, property path such as $.contact.email, type, values of an enum) and the tags of its rows |
find_data |
Data matching the rules, one page at a time (up to 100 rows), with sorting; limit: 0 only counts |
get_data |
Data by ids |
reserve_data |
Reserves free rows matching the rules for the user, so parallel tests and agents never get the same row |
release_data |
Releases reserved rows by ids |
insert_data |
Inserts rows (up to 100; all of them or none) and returns them with their ids |
update_data |
Changes rows selected by ids or rules: sets or removes properties, sets the tag, reserves or releases |
delete_data |
Deletes rows, with their history, selected by ids or rules - ROBOT or higher |
search_history |
The changes of the rows matching the rules, filtered by who and when changed them, optionally with the properties of each version (buckets with history) |
Rules are the same as in the API version 2 (see Rules): a list of [left, operator, right], e.g. [["$.account.status", "==", "active"], ["reserved", "==", false]]. Rules given as SQL text are refused.
When a call fails, the agent gets a message that says what to do instead, e.g. There is no bucket 'customers' you have access to; see list_buckets.
- Find in dev-users an active premium customer from Germany and reserve them for my test.
- Release all the rows I reserved in int-users.
- Who changed user 125 in dev-users last week, and what did they change?
- Add 5 test customers from Poland to dev-users, with the tag "new".
Agents make mistakes: give the agent a user with access only to what it needs, prefer the AGENT role, and keep the history on in the buckets it changes, so every change can be checked.
Wiki
Work in the project
- Navigation
- Overview
- Searching
- Filtering
- Create/modify/remove data
- Data reservation
- Data details
- Data history
- Tasks execution
- Data export
- Data import
Project settings
Management
API