Connecting Betterplan to an AI agent (MCP)
Betterplan offers an MCP server (Model Context Protocol). It lets an AI assistant such as Claude work with Betterplan on your behalf: read projects and tickets, create and change tickets, comment, or query iterations and insights. You stay in the AI's interface and don't have to copy tickets over by hand.
This feature is being rolled out gradually. If you don't see it yet, it hasn't been enabled for your account. Without access a client can connect but gets no tools, and its calls are rejected.
How the connection works
The MCP server runs separately from the Betterplan app at its own address. For the hosted version that address is https://mcp-app.yourbetterplan.com. If you run Betterplan yourself or use another instance, use the address your administrator gives you.
Sign-in uses OAuth. You don't give the AI client a password; you grant it access once:
- You enter the MCP server address in the AI client.
- The client opens your browser. If you aren't signed in to Betterplan, you sign in first.
- Betterplan shows the Authorize access page. It names the requesting application and the permissions it asks for, for example your identity and email address.
- Allow grants access, Deny refuses it. You are then returned to the client automatically.
The authorization page is currently available in English only, even if Betterplan is set to German. There is no screenshot here because the page only shows content inside a real authorization flow.
Connecting with Claude
Exact menus differ by client and version. When in doubt, follow the client's own guide to remote MCP servers or connectors. The principle is always the same: you add a remote MCP server by URL and finish sign-in in the browser.
- Claude (web and desktop): In the settings, add a custom connector under Connectors, enter the MCP server address and follow the sign-in.
- Claude Code: Add the server as an HTTP server with
claude mcp add, for exampleclaude mcp add --transport http betterplan <MCP-URL>. Replace<MCP-URL>with the address given above. Then start the sign-in for the server with/mcpinside the program. - Other clients: Any client that supports remote MCP servers with OAuth works the same way.
Once connected, ask the agent to call the ping tool first. It takes a message (message) and answers with your account's email address and your message, confirming connection and sign-in.
What an agent can do
An agent only works with the tools the server offers. Currently these, grouped by area:
| Area | Tools | Effect |
|---|---|---|
| Connection | ping | Checks connection and sign-in, read-only |
| Projects | list_projects, get_project, create_project, update_project | List and read projects, create new projects, change project settings |
| Tickets | list_tasks, get_task, create_task, update_task, list_task_references | Search and read tickets, create and change them, find mentions (#number) of a ticket in other tickets, discussions and activity |
| Comments | list_task_comments, create_task_comment | Read and write comments |
| Discussions | get_discussion, create_discussion, add_discussion_comment | Read, start and answer discussions |
| Dependencies | list_dependencies, create_dependency, delete_dependency | Read and create dependencies, delete them |
| Buckets | get_bucket, create_bucket, update_bucket | Read, create and change buckets |
| Releases | get_release, create_release, update_release, delete_release | Read, create and change releases, delete them |
| Iterations | list_iterations, get_iteration | Read iterations, read-only |
| Insights | get_progress_insights, get_flow_insights | Query progress analysis plus cycle time, lead time and throughput |
| Attachments | list_attachments, get_attachment_download_url, get_attachment_thumbnail_url, upload_attachment, delete_attachment | List attachments, get download links, upload and delete |
| Team | list_my_teams, list_team_members | Read your teams and their members |
How a client shows the tools varies. Many ask for your confirmation before write calls.
An agent finds a ticket with list_tasks using the ticket number (#570) or filters such as type, state, tag or title. That is far cheaper than loading the whole project with all descriptions.
Security and permissions
- The agent has your permissions. It acts under your account and can only see and change what you can see and change yourself. If you only have read access to a project, it can't write there. More in Teams and roles.
- Write tools change real data. That includes creating, changing and deleting tickets, releases, dependencies and attachments. An agent can be wrong. Check what it intends to do before you approve write calls, and when in doubt let it read first.
- Don't share the access. It is granted to you. Don't pass a client's credentials on to others.
- Sign-in expires. The client's access token is time-limited (about an hour). After that you may need to sign in again (some clients renew access automatically); the client then takes you through the authorization once more.
Revoking access
Remove the Betterplan server in the AI client (disconnect the connector or delete the MCP server) and don't let the client sign in again. Without a valid token it can't retrieve anything. A token already issued stays valid until it expires. If you need immediate revocation, contact support.
Betterplan skills for agents
Besides the MCP server there are Betterplan skills: instructions that teach an agent how Betterplan is meant to be used so it creates tickets in the right shape. They use the MCP server when it's connected and otherwise output Markdown to paste.
| Skill | Purpose |
|---|---|
betterplan-workflow | Classifies work into the right building block and holds the shared rules |
betterplan-create-initiative | Phrases and creates an initiative |
betterplan-create-epic | Creates an epic under an initiative |
betterplan-create-story | Creates a user, project or devteam story |
betterplan-create-workitem | Breaks a story into workitems and records bugs |
betterplan-implement-story | Has a coding agent implement stories tagged project:Agent in the current iteration and keeps the Iteration Board up to date |
The skills and their installation (Claude Code and other agents) are described at github.com/yourbetterplan/skills. More about the method behind them in the Method section.