Use other AI tools with an agent token

Besides your agent in the app, you can let other AI tools work with buildIt.social: Claude Desktop, Cursor, VS Code, Claude Code without the plugin, and other MCP clients. They connect through buildit-mcp, our open-source MCP server, with a personal agent token you create.

A token works as you, with only the permissions you choose. What a tool does with it shows as yours, “via” the token’s name, such as “Kelly (via Claude Code (Windows))”.

Before you start#

An org owner or admin must turn on agent access first. Until then, Settings → Agent tokens says “Agent access is off for this organization. Ask an owner or admin to turn it on.”

Guests can’t create agent tokens.

Create a token#

1. Open Settings → Agent tokens and tap Create token.
2. Enter a Name, such as “Claude Code (Windows)”, up to 40 characters. History shows what the tool does as “via” this name.
3. Under Permissions, choose what it may do:
   • Read projects: items, comments, history, sprints and releases.
   • Work on projects: create and edit items, change status, assign, comment and link.
   • Delete and move items (Sensitive): delete and move items, update many at once and archive statuses, after a preview you confirm.
   • Manage project setup (Sensitive): change workflows, work types, fields and labels, after a preview you confirm. Needs project admin.
   • Read pages and Edit pages: channel pages.
   • Read channels: messages and threads in your channels. Never direct messages.
4. Under Limits (optional), you can limit it to Only chosen projects and Only chosen channels. With projects chosen and no channels, its messages and pages are limited to those projects’ channels.
5. Under Expires after, choose 7, 30, 90 or 365 days. 90 is the default; a token never lasts forever.
6. Tap Create.

Copy it now#

The token is shown once: “Copy this token now: it won’t be shown again. If you lose it, revoke it and create a new one.” Tap Copy token. Tokens start with buildit_pat_.

Keep it out of files. Put it in an environment variable named BUILDIT_TOKEN in your user environment or shell profile, never in a file in a repository. Set up Claude Code shows the lines to add to a project’s .mcp.json, which read the token from that variable; tap Copy setup.

Set up your tool#

Each tool starts buildit-mcp with npx, which downloads it the first time. The buildit-mcp guide on GitHub has the exact setup for each:

• Claude Code: claude mcp add buildit --scope user -e 'BUILDIT_TOKEN=${BUILDIT_TOKEN}' -- npx -y @kammcs/buildit-mcp@latest, or the .mcp.json from Copy setup.
• Cursor and VS Code: a short mcp.json. VS Code can ask for the token once and keep it in its secret storage.
• Claude Desktop: install the bundle from the latest release. Claude Desktop asks for the token and keeps it in your system’s secure storage.

Then ask the tool to run whoami on buildit to check the connection: it says who the token acts as and what it may do.

By default, the tools for items and comments are on. The guide explains how to turn on planning, pages, chat, admin and destructive changes.

Big changes need your yes#

With a token, deleting, moving or bulk-editing items, archiving a status, and changing workflows, work types, fields or labels never happen in one step. The tool first gets a preview of exactly what would change and shows it to you. Only when you say yes in that conversation does it make the change, and the preview works once, for 10 minutes. If anything changed in the meantime, it has to ask you again.

This is different from your agent in the app, whose changes wait for your tap on an Apply card. See Apply cards.

What a token can’t do#

• Read direct messages. Ever.
• Read or share files. Files are for your agent’s sessions only.
• Manage agent access or other tokens.
• Work in another organization. Each token belongs to one organization.

Manage your tokens#

Settings → Agent tokens lists Your tokens, each with its status, when it was last used and when it expires, with “Expires in 3 days” in its last week. Below them, Your agents’ activity lists the calls your tokens made.

• Revoke stops a token at once: “Agents using this token stop working at once. This can’t be undone.”
• A week before a token expires, you get an entry in Work → Inbox: “Your agent token expires on” the date.
• You can have up to 10 active tokens in an organization.
• Your agent’s sessions show in the list too, marked “Session of Claude”. Revoking one revokes that session.