Connect an AI agent

Before you start

You need a Tickhatch account with at least one board you own or can edit, and an agent that speaks MCP — Claude Code, Cursor, or any client that supports the streamable HTTP transport with custom headers. There’s nothing to install on the Tickhatch side.

Mint a token

1. 1

   Open Settings → Agent access

   In Tickhatch, open Settings (from the dashboard header) and find the Agent access section.

2. 2

   Name it and pick a scope

   Name the token after the agent that will hold it — claude-code, cursor — so the audit trail reads well. Pick an Access level: Read, Write, or Write + ship (see Scopes below — Write is the right default). Optionally pin it to one Board: a pinned token can’t see or touch anything else. Leave it on All boards to let the agent roam.

3. 3

   Create the token and copy it

   Press Create token and copy the tkh_… value into your agent’s config.

   Heads up

   The raw token is shown once — Tickhatch stores only a SHA-256 hash, so it can’t be recovered later. If you lose it (or an agent leaks it), revoke it in Settings → Agent access and mint a new one.

Add it to your agent

Tickhatch speaks MCP over streamable HTTP at https://tickhatch.com/api/mcp, with the token in a standard Bearer header.

Claude Code

One command, run anywhere:

claude mcp add --transport http tickhatch https://tickhatch.com/api/mcp --header "Authorization: Bearer tkh_YOUR_TOKEN"

Cursor

Add the server to your project’s MCP config:

{
  "mcpServers": {
    "tickhatch": {
      "url": "https://tickhatch.com/api/mcp",
      "headers": {
        "Authorization": "Bearer tkh_YOUR_TOKEN"
      }
    }
  }
}

Any other MCP client

Anything that supports MCP’s streamable HTTP transport with custom headers works the same way: point it at https://tickhatch.com/api/mcp and send Authorization: Bearer tkh_YOUR_TOKEN on every request.

Scopes

Every token carries one of three access levels:

The gap between write and ship is deliberate. An agent can plan, claim, build, and hand work over for testing — but marking something shipped stays with a merged PR or a human. Give agents Write by default and reserve Write + ship for the rare agent that genuinely deploys. A few rails hold regardless of scope: a Read token calling any write tool is told “This token is read-only.”, a token never exceeds your own role on a board (a board you can only view answers writes with “You have read-only access to KEY.”), and every call is audited and rate-limited to 60 requests per minute per token.

What agents can do

Ten tools, small on purpose — enough to run the whole New → In Progress → Testing loop without handing over the keys to everything:

A loop that works

The tools are shaped for a simple, safe working rhythm:

1. next_ticket hands back the single best unclaimed ticket, full detail included.
2. claim_ticket assigns it and moves New → In Progress. If someone (or some agent) got there first, the claim fails cleanly — just ask for the next ticket again.
3. Do the work.
4. comment progress along the way, so the board tells the story.
5. move_ticket to testing when it’s ready for eyes.

If the agent gets stuck, release_ticket puts the ticket back in the pool for someone else. And the last hop stays out of the agent’s hands: a human — or a merged pull request via GitHub auto-ship — moves it to In Production.

Troubleshooting

More guides