Connect your own AI agent

Connect an AI agent (Claude Code, Claude Desktop, Cursor, or any MCP client) to a TaskPebble project. The agent reads the project's priorities and rules, works the tasks you give it, posts its work as comments, and hands finished work back to a person for review. Every change it makes is labelled in the activity history.

This guide is for organization admins and developers. It takes about 15 minutes.

What you need

• A TaskPebble organization on the Personal, Team or Business plan. API tokens aren't available on Free.
• Admin rights on the project the agent will work in. You need them to set the agent's rules.
• An MCP-capable agent: Claude Code, Claude Desktop, Cursor, or another MCP client.

How it works

Step 1: Set the project's rules

Open the project, click the gear icon, and find AI agents.

1. Instructions: tell the agent what matters, for example: "Work the highest-priority task first. Keep comments short. Ask in a comment before anything that affects billing, legal text or customers."
2. Work on first (optional): pick a deliverable the agent should focus on.
3. Rules:
   • Agents can add tasks and subtasks: on by default.
   • Agents can mark tasks done or cancelled: off by default, so agents move finished work to In review and a person closes it. We recommend leaving it off.
   • Agents can change deliverables: off by default.
4. Click Save.

Agents can't change these settings themselves, whatever token they use.

Step 2: Create a token for the agent

Go to Profile → API tokens → Generate token:

Copy the token (it starts with pmapp_). It's shown only once. Treat it like a password: put it in your agent's configuration, not in chats, tickets or code.

Create one token per agent. Each token appears separately in assignee menus and the activity history, and you can revoke one without affecting the others.

Step 3: Connect your agent

Replace pmapp_YOUR_TOKEN with the token from step 2. Claude Code has been tested end to end. The Cursor and Claude Desktop setups follow those tools' documented formats; if one doesn't connect, check its current MCP documentation.

Claude Code

claude mcp add --scope user --transport http taskpebble https://taskpebble.com/api/mcp/ \
  --header "Authorization: Bearer pmapp_YOUR_TOKEN"
claude mcp list   # should show taskpebble: connected

Leave out --scope user to add it only for the current folder.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

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

Claude Desktop

Claude Desktop's custom connectors don't take a fixed header, so use the mcp-remote bridge (needs Node.js). In claude_desktop_config.json:

{
  "mcpServers": {
    "taskpebble": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://taskpebble.com/api/mcp/",
               "--header", "Authorization:${TASKPEBBLE_AUTH}"],
      "env": { "TASKPEBBLE_AUTH": "Bearer pmapp_YOUR_TOKEN" }
    }
  }
}

Restart Claude Desktop afterwards.

Any other MCP client

• Transport: Streamable HTTP
• URL: https://taskpebble.com/api/mcp/ (keep the trailing slash)
• Header: Authorization: Bearer pmapp_YOUR_TOKEN

Step 4: Give the agent work

• Assign tasks: in any task's Assignee menu, the agent appears under AI agents with its token name. Tasks assigned to it come first in its queue.
• Ask it to start: in your agent, say "Get the TaskPebble brief and work the next task." The agent will:
  1. read the brief and pick the top task
  2. move the task to In progress and assign it to itself
  3. post its work and a "Progress:" summary as comments
  4. move the task to In review when it's finished, or back to To do with a "Not done yet. Needs: …" comment when it needs something it can't do (code, a deploy, a decision)
• Review: open the task, read the comments, and close it or send it back with notes.

Changes made by the agent show "via <agent name>" in the task activity. The project's gear → AI agents panel lists recent agent changes.

Step 5 (optional): Start the agent automatically

The TaskPebble agent watcher starts Claude Code in the background whenever a person moves one of the agent's tasks to In progress. It runs on a computer you control (a Linux machine with systemd and Claude Code installed and signed in) and checks every minute.

1. Copy watcher.py from TaskPebble's tools/agent-watcher/ to ~/.local/share/taskpebble-agent/ on that machine.
2. Create ~/.local/share/taskpebble-agent/mcp.json (readable only by you: chmod 600):

   {"mcpServers": {"taskpebble": {"type": "http", "url": "https://taskpebble.com/api/mcp/",
     "headers": {"Authorization": "Bearer pmapp_YOUR_TOKEN"}}}}

3. Check it: python3 ~/.local/share/taskpebble-agent/watcher.py --dry-run prints the agent and project it found.
4. Install the systemd timer from tools/agent-watcher/ (see its README), then run:

   systemctl --user enable --now taskpebble-agent.timer

5. Move a task assigned to the agent to In progress. Within a minute or two, ~/.local/share/taskpebble-agent/agent.log shows the run, and the task's comments fill in.

The watcher runs Claude with no shell, file or web access, only the TaskPebble tools. It does one task at a time, with a 20-minute limit. Only finished work goes to In review. If the task needs something the agent can't do with TaskPebble tools (code, a deploy, an account, a decision), the agent posts its plan, says what's needed, and moves the task back to To do. A run that ends early is moved back to To do too, so nothing stays stuck in In progress. The machine must be on for it to work; an always-on server is best.

Safety at a glance

• Agents can't:
  • delete anything (with a "no deleting" token)
  • reach other projects (with a single-project token)
  • change their own rules, or touch account, billing or org settings
• By default, agents can't mark tasks done or edit deliverables. People approve the work.
• Rate limits: each token is limited to 120 requests and 60 changes a minute, and 5,000 requests a day.
• Tokens expire after a year at most. Revoke one any time in Profile → API tokens.
• Task text isn't trusted: the brief tells agents to treat it as information, not instructions. Even so, only connect agents to projects whose content you trust.

Troubleshooting

FAQ

Does the agent take a seat on our plan?
No. Agents are named assignees, not user accounts.

Who pays for the AI?
Your agent runs on your own Claude, Cursor or other subscription. TaskPebble doesn't charge for agent requests.

Can several agents work the same project?
Yes. Give each its own token and assign tasks to the one you want.

Can the agent work in our code?
TaskPebble only gives it project-management tools. An agent like Claude Code can also work in your code if you run it in your repository with its own tools enabled. The optional watcher deliberately doesn't.

Claude is a trademark of Anthropic and Cursor of Anysphere. TaskPebble isn't affiliated with either.