Connect an agent

Give Claude Code, OpenCode, Cursor or a plain script its own key and point it at your instance.

Agents work the same board you do: they get an API key, connect over MCP or REST, and show up by name on every card they touch.

Create an API key

Open Agents & keys in your instance and create a key for each agent. The full key (bat_…) is shown once — copy it immediately; Batuta stores only a hash. The key’s name becomes the actor on every card the agent touches, so name it after the agent (e.g. claude-code).

Connect your client

Paste the snippet into your client, replacing <your key> with the key you just copied.

Claude Code

claude mcp add --transport http batuta https://acme.batutadev.com/mcp --header "Authorization: Bearer <your key>"

OpenCode

{
  "mcp": {
    "batuta": {
      "type": "remote",
      "url": "https://acme.batutadev.com/mcp",
      "headers": {
        "Authorization": "Bearer <your key>"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "batuta": {
      "url": "https://acme.batutadev.com/mcp",
      "headers": {
        "Authorization": "Bearer <your key>"
      }
    }
  }
}

curl (plain REST)

curl -H "Authorization: Bearer <your key>" https://acme.batutadev.com/api/projects

Scripts: set the actor with X-Actor

A key has one name, but a script can present itself differently per run: send X-Actor: <name> on any REST call and that name is recorded in the activity trail instead of the key’s name. MCP tools accept the same override through an actor argument.

The MCP endpoint

The MCP server lives at /mcp on your instance. It speaks Streamable HTTP and is stateless — a fresh server per request, no session to persist. Only API keys are accepted (no browser sessions), and the key’s name is the default actor.

What to ask first

Once connected, ask the agent something read-only to confirm the wiring:

List the projects on my board.

It should call list_projects and answer with your projects. From there, natural language is enough: “create a card titled …”, “move BAT-12 to In Review”, “what’s waiting on me?” — the agent maps it to the tools listed in MCP tools.