Skip to content

AI agents

Krzysztof Słysz edited this page Nov 16, 2026 · 2 revisions

AI agents (MCP)

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.

Enable the MCP server

The MCP server is off by default. Switch it on in the configuration (see Installation):

databucket:
  mcp:
    enabled: true

or 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.

A user for the agent

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.

Get a token

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/signin

Copy 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.

Connect the agent

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.

Tools

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.

Example prompts

  • 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.

Clone this wiki locally