How do I connect an AI agent to BoardMark?
Add BoardMark as an MCP server and sign in through your browser — no token to copy. Or use a personal access token for CI and machines without a browser. The agent works with exactly your rights — only your projects, never admin.
user parity — never admin
Option 1 · Browser sign-in (recommended)
Add BoardMark as an MCP server
In Claude Code, run (Streamable HTTP) — no token needed:
Claude Code claude mcp add --transport http boardmark https://mcp.boardmark.ai/mcpSign in and choose the company
Claude Code opens your browser to sign in to BoardMark and choose the company the agent works in. (If no browser opens, run /mcp in Claude Code and pick this server to sign in.) Each sign-in is for one company.
See and revoke it any time
Signed-in apps are listed on the Agent & MCP access page of the web app. Sign one out and it loses access immediately.
Open the web app
Option 2 · Personal access token (CI)
Create a token in the app
On Agent & MCP access, create a new token, name it and pick 30, 90, 180 or 365 days. Tokens start with board_pat_ and are shown once — store it somewhere safe. Revoke it any time.
Keep the token in an environment variable
Never put the token in a file you commit to git.
shell export BOARD_PAT="board_pat_…"Add the MCP server with the header
For Claude Code:
Claude Code claude mcp add --transport http boardmark https://mcp.boardmark.ai/mcp --header "Authorization: Bearer $BOARD_PAT"Or add it to the project's .mcp.json (Claude Code expands ${BOARD_PAT} from the environment):
.mcp.json { "mcpServers": { "boardmark": { "type": "http", "url": "https://mcp.boardmark.ai/mcp", "headers": { "Authorization": "Bearer ${BOARD_PAT}" } } } }
Which rules do agents follow?
- Every write sends a version — always call get_issue before update_issue. If someone changed it first you get 409 version_conflict instead of an overwrite.
- They know the three board types — Scrum has sprints (several may run at once), Kanban and Delivery pipeline have none, and a pipeline's statuses follow the environments in project.md.
- Every write is recorded — commits made over MCP carry the agent token; in the app, agent cards, comments and uploads are badged.
- 600 requests/minute per token — by default.
- Agents are not seats — they use the rights of the user who connected them and cost nothing extra.
Which tools are there? (31 tools)
Every tool maps 1:1 to the public API and is permission-checked exactly like the web app.
Projects & my work
| Tool | What it does |
|---|---|
list_projects | Projects you can access, optionally with an overview (open issues, running sprints and their progress) in one call |
list_my_issues | Issues assigned to you across every project, in one call |
get_project | project.md: board type, statuses, workflow, environments and your role |
Issues
| Tool | What it does |
|---|---|
search_issues | Search by status, assignee, sprint, type, label, text, parent (paginated) |
get_issue | Read an issue with its current version |
create_issue | Create an issue (one .md file) |
update_issue | Change any number of fields in one call — requires version |
delete_issue | Delete an issue — requires version |
transition_issue | Move to another status (including each environment's statuses on a pipeline) |
rank_issue | Order an issue (before/after another) |
assign_issue | Set the assignee |
link_issues | Link issues (blocks, relates, duplicates, clones) |
unlink_issues | Remove a link |
Comments & attachments
| Tool | What it does |
|---|---|
list_comments | Comments on an issue, with reply threads |
add_comment | Add a Markdown comment or reply to one |
request_upload | Get a presigned upload URL |
attach_file | Attach an uploaded file to an issue |
list_attachments | An issue's attachments: name, size, date and uploader |
get_download_url | Presigned download URL for an attachment |
Sprints
| Tool | What it does |
|---|---|
list_sprints | Sprints of a project (several may be active) |
create_sprint* | Create a sprint |
update_sprint* | Rename a sprint or change its dates or goal |
move_to_sprint | Move issues into or out of a sprint |
start_sprint* | Start a sprint |
close_sprint* | Close a sprint and move unfinished work |
get_burndown | Sprint burndown (Scrum) |
The md tree
| Tool | What it does |
|---|---|
read_file | Read an .md file |
write_file | Write an .md file through the same validator as the UI |
list_dir | List files in the md tree |
get_history | Commit history: who changed what, and through which agent token |
diff | Diff two versions |
MCP resources
board://{project_key}/project.mdboard://{project_key}/issues/{key}
* requires project_admin
What can an agent never do?
MCP has no admin or billing tools at all. These stay in the web app, for the people whose role allows them:
MCP questions
How do I connect an AI agent to BoardMark?
The easiest way: add the MCP server in Claude Code, then sign in through your browser and choose the company — no token to copy. For CI or machines without a browser, create a personal access token in the app and send it as the header Authorization: Bearer <token>.
Can an agent safely edit an issue someone else is editing?
Yes. Every write sends the version of the file it read. If someone changed it first, the server answers 409 version_conflict instead of overwriting, so agents should always call get_issue before update_issue.
How do I see what an agent changed?
Every agent write records the token in its commit. In the app, cards and attachments changed or uploaded by an agent carry a badge, and the Agent & MCP page lists your agents' recent commits.
Is there a rate limit?
Yes — 600 requests per minute per token by default.