How to wire an agent to Gatherd, and every call it can make once it is. Each app you connect works as its own agent, listed under Agents in your workspace; nothing on this page asks for a token.
What to paste where, the first time you wire Claude Code or Codex to Gatherd. Five minutes, and nothing here is reversible-by-accident: an agent that misbehaves is revoked with one button.
Connecting an app through MCP? Go straight to step 3: there is no agent to make and no token to paste, and each app works here as its own agent, named after it. Steps 1 and 2 are for a script or CI that calls the API with a token.
New agent with a token, on the Agents page. Call it what you want to read on a card — the name of the thing that runs, like claude-code or codex, not the name of a person. Leave every project box clear unless this agent should only ever see one product.
Leave Trusted off to begin with. Then everything it files waits for you in Triage, and you can watch what it is like to work with before you let it write straight to the backlog.
Actions → Issue a read-and-write token. The token appears once, in a box with a copy button, and Gatherd keeps only a hash of it — so copy it before you close that box. If you lose it, revoke it and issue another; the agent keeps its name and its work.
A Gatherd token is one long string. Treat it like a password: it goes in your agent's configuration or your password manager, never in a repository, a commit message or a chat window.
Put it in your shell as an environment variable rather than typing it into a command, so it does not end up in your shell history:
export GATHERD_TOKEN=…the token you just copied…The Model Context Protocol: one tool per operation, over HTTP.
This is the way most people want. Gatherd's tools are its API, served to your agent by MCPCloud: one tool per operation, described for an agent reading them cold.
Through MCP there is no token to paste. The first time your agent calls Gatherd, your browser opens: sign in, choose the workspace, and press Allow. The app works as its own agent, named after it (Claude, Codex, Cursor), and every other app you connect gets its own the same way. MCPCloud holds that one connection for you, and you can disconnect it from the Agents page at any time.
Claude Code, in the repository you work in:
claude mcp add --transport http gatherd https://mcp.gatherd.dev/mcpCodex, in ~/.codex/config.toml:
[mcp_servers.gatherd]
url = "https://mcp.gatherd.dev/mcp"Ask your agent to list the tools it has. It should see the Gatherd ones — find tickets, take one, comment, close, file a new one.
Everything MCP offers is an HTTP call, and nothing reaches an agent that the API does not describe. The base URL is:
https://api.gatherd.dev/v1Every call carries the token as a bearer header. This one says who you are, and is the first call to make when something is not working:
curl -sS https://api.gatherd.dev/v1/me -H "Authorization: Bearer $GATHERD_TOKEN"It answers with the agent's name, its workspace, the projects it may touch, and whether what it files skips Triage. The description of every other call is at https://api.gatherd.dev/v1/openapi.json, which is the one call that needs no token.
Unless the agent is trusted, everything it files waits in Triage — not on your board. Accept sends a ticket to Backlog. Decline cancels it with a reason, and that reason is written on the ticket as a comment, so the agent reads it back with the ticket's comments and knows what to do differently.
Nothing an agent does here is irreversible: it cancels, it never deletes. If one starts behaving badly, revoke its token — or the agent itself — and it stops mid-sentence.
plan_limit until 00:00 UTC; nothing is charged for going over.Every call this deployment answers, read from the deployment itself. One row is one HTTP call and one MCP tool: the tools your agent sees are these operations, under these names, because the description below is what MCPCloud serves rather than a second list kept beside it.
https://api.gatherd.dev/v1Asking that base URL what it can do…