Docs / AI
AI agents & MCP
Let coding agents like Claude Code, Cursor or Codex read your board, pick up tickets, comment, attach screenshots and move work forward. Access goes through scoped tokens that you can revoke at any time.
Create a token
Open AI Access
Go to Settings → AI Access and create a token.
Choose its scopes and reach
Give the token only the scopes the agent needs, and optionally limit it to one workspace or project. It can never do more than you can.
Copy it once
The token is shown only once. Copy AI instructions gives you a block to paste into any AI chat or IDE, and Copy repo setup gives you an
.mcp.json. Revoking the token cuts off the agent immediately.
Connect your agent
Planytic runs an MCP server at https://api.planytic.com/mcp. Any MCP client can use it.
Claude Code
claude mcp add --transport http planytic https://api.planytic.com/mcp \ --header "Authorization: Bearer <your-token>"Cursor and other clients
{ "mcpServers": { "planytic": { "url": "https://api.planytic.com/mcp", "headers": { "Authorization": "Bearer <your-token>" } } }}Local server
For clients that only support local (stdio) servers, run the package with npx. It can also upload files straight from your disk.
{ "mcpServers": { "planytic": { "command": "npx", "args": ["-y", "github:planytic/planytic-mcp"], "env": { "PLANYTIC_TOKEN": "<your-token>", "PLANYTIC_URL": "https://api.planytic.com" } } }}Scopes
| Scope | Allows |
|---|---|
projects:read | Listing and reading projects |
tickets:read | Reading tickets, comments, board columns and linked pull requests |
tickets:write | Creating, updating and moving tickets, logging work, uploading attachments |
comments:write | Commenting on tickets |
documents:read | Reading project documents |
documents:write | Creating and editing documents |
A 403 error means the token is missing a scope or can't reach that project. Scopes are fixed when a token is created, so create a new token with the right scopes and revoke the old one.
Tools
| Area | Tools |
|---|---|
| Orientation | whoami, get_manifest, list_workspaces, list_projects |
| Boards | list_boards, get_board, list_epics, list_labels, list_members |
| Tickets | list_tickets, get_ticket, create_ticket, update_ticket, move_ticket, export_ticket |
| Collaboration | add_comment, upload_attachment, log_work |
| Documents | list_documents, list_document_categories, read_document, create_document, update_document |
Without MCP: the REST API
Agents that can't use MCP can call the REST API directly with the same token. Everything starts from a manual written for AIs:
| URL | What it is |
|---|---|
GET /api/ai/useme | The API manual: every endpoint, scope and rule. Markdown by default, JSON with Accept: application/json. Public, and with a token it also says whose account the agent acts for. |
GET /api/ai/whoami | Who the token belongs to, its scopes, and the projects it can reach. Needs a token. |
Send the token only in the Authorization: Bearer header, never in a URL.
Hand a ticket to an agent
On any ticket, open the ⋯ menu and choose Export to AI. This copies a prompt like the one below. Paste it into your agent and it fetches the ticket's full work packet: the description, details, labels and comments, plus the endpoints for commenting on, updating and moving the ticket.
Work on this Planytic ticket: https://api.planytic.com/api/v1/tickets/<id>/exportAPI manual: https://api.planytic.com/api/ai/usemeAsk me for an agent token, then send it as Authorization: Bearer <token> (header only, never in URLs).Fetch the export URL for the full work packet + write-back endpoints.How agents should work
Planytic gives connected agents these rules, so their work stays easy to follow:
- Start with
whoamito see who the token belongs to and what it can do. - Leave a comment that explains a move before moving a ticket.
- Fill in the ticket's
ai_contextwhen finished, so the next person or agent can pick up the work. - Never delete anything. Agents have no delete tools.
Seeing what agents did
- Agents act as the person who owns the token, and everything they do appears in the ticket's activity.
- Comments and logged work from agents are marked as AI and show the token's label, for example Claude Code (AI, for Xavier).
- When an agent finishes, the summary it writes appears in the ticket's AI context panel, so the next person or agent can pick up from there.
Uploading attachments
upload_attachment adds a screenshot, recording or file to a ticket. It returns a markdown snippet; put that snippet in a comment or description to show the file inline.
- Hosted server: send the file as base64
content. - Local npx server: pass a file
pathinstead. - Images can be up to 5 MB and videos up to 25 MB.
Treat tokens like passwords
Never commit a token to a repository. Put it in your MCP client's configuration or an environment variable, and revoke it in AI Access if it leaks.