BoardMark

npx add-mcp 'https://mcp.boardmark.ai/mcp'

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

Send one link to any AI assistant

The guide for AI agents is one Markdown file: what BoardMark is, how to use it step by step, the rules, prices and the FAQ. Paste the link into ChatGPT, Claude, Gemini, Copilot or any other assistant and it can help you use BoardMark right away, with or without MCP. If the assistant supports MCP, the guide also shows it how to connect.

Guide for AI agents

https://www.boardmark.ai/agents.md

Or paste this message

Guide for AI agents

Read https://www.boardmark.ai/agents.md and help me use BoardMark.

Open the guide (agents.md)

1. Add BoardMark as an MCP server

   In Claude Code, run (Streamable HTTP) — no token needed: Claude CodeCopy

   claude mcp add --transport http boardmark https://mcp.boardmark.ai/mcp
   

2. Sign 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.

3. 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

4. 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.

5. Keep the token in an environment variable

   Never put the token in a file you commit to git. shellCopy

   export BOARDMARK_TOKEN="board_pat_…"
   

6. Add the MCP server with the header

   For Claude Code: Claude CodeCopy

   claude mcp add --transport http boardmark https://mcp.boardmark.ai/mcp --header "Authorization: Bearer $BOARDMARK_TOKEN"
   

   Or add it to the project's.mcp.json (Claude Code expands ${BOARDMARK_TOKEN} from the environment): .mcp.jsonCopy

   {
     "mcpServers": {
       "boardmark": {
         "type": "http",
         "url": "https://mcp.boardmark.ai/mcp",
         "headers": {
           "Authorization": "Bearer ${BOARDMARK_TOKEN}"
         }
       }
     }
   }
   

• Claude Code
• Claude Desktop
• claude.ai
• OpenAI Codex CLI
• ChatGPT
• Google Antigravity
• Gemini CLI
• xAI Grok
• Goose
• OpenCode
• Cursor
• VS Code (GitHub Copilot)
• Windsurf
• Kiro
• Zed
• Cline
• Continue
• LM Studio
• Mistral Le Chat
• Microsoft Copilot Studio

Clients that can only run local (stdio) servers connect through mcp-remote.

MCP setup for every client (connect.md)

Let your agent set itself up

Paste this into the agent — it reads the guide and follows the steps for the client it is running in:

Prompt for your agent

Connect yourself to BoardMark: read https://mcp.boardmark.ai/connect.md and follow the steps for the client you are running in.

• 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 read the project docs first — get_project says which docs to read first (docs.read_first), or get_docs_context returns the brief, working notes and open handoffs in one text. The company's and project's rules there come before BoardMark's defaults (the user's instruction comes first), so a team writes its rules once and every agent follows the same ones.
• 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.
• On Scrum, people start sprints — an agent changes status only for issues in a sprint a person has started (otherwise 409 sprint_not_started) and cannot start a sprint itself; it can still plan the backlog, comment and edit other fields.
• They follow the board's columns — get_project gives each column's category, colour, WIP limit and meaning (Premium companies customise columns in the web app); agents follow the meaning and treat a WIP limit as a warning. 403 plan_required means the feature needs the Premium plan — a company admin upgrades in the web app.
• Every write is recorded — issue and doc history shows whose rights, which AI client (for example “via Claude Code”), OAuth or token, which MCP tool and a request id; in the app, agent cards, comments and uploads are badged, and requests BoardMark refused go to the company's Audit log.
• 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.

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 and template, statuses with each column's category, colour, WIP limit and meaning, custom field definitions, saved filters, workflow, environments, your role, and on Scrum sprint_control (admins or members: who can press Start sprint)

Issues

Tool	What it does
search_issues	Search by status, assignee, sprint, type, priority, label, text (title, description or issue key, whole or part), parent, custom fields (fields), template flags (flag, such as overdue or off_track) and issues linked to a key (linked_to=KEY-n); sort by priority or a field (paginated)
get_issue	Read an issue with its current version, computed field values (computed, such as score and progress) and its live linked targets (linked: key, title, status or a release's state + progress; readable: false when you have no access)
create_issue	Create an issue (one.md file), with the template's custom field values (fields)
update_issue	Change any number of fields in one call, custom fields included (fields key by key, null clears) — requires version
delete_issue	Delete an issue — requires version
transition_issue	Move to another status (including each environment's statuses on a pipeline) — on Scrum only for issues in a sprint a person has started, else 409 sprint_not_started
rank_issue	Order an issue (before/after another)
assign_issue	Set the assignee
list_people	Who can open the project, with names and roles — name the reporter or assignee and find ids to @mention (via: "company" marks people in through company-wide access)
list_watchers	Who watches an issue, and whether you do
watch_issue	Watch an issue to get emails on status changes and new comments
unwatch_issue	Stop watching an issue
link_issues	Link issues (blocks, relates, duplicates, clones) — takes the key of another project in the same company, and delivers to a release with id KEY/R-n (403 link_target_forbidden, 404 release_not_found)
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 — mention people with [@Name](mention:usr_…) — ids from list_people (only project members are emailed); you then watch the issue
update_comment	Edit your own comment — requires version
delete_comment	Delete a comment (leaves “This comment was deleted”, replies stay) — requires version
request_upload	Get a presigned upload URL
attach_file	Attach an uploaded file to an issue — show an image inline with (no base64)
list_attachments	An issue's attachments: name, size, date and uploader
delete_attachment	Delete an attachment for good — only files this same token uploaded; links in the description and comments then show “file deleted”
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 — people only: an agent token gets 403, so ask the user to press Start sprint in the app
close_sprint*	Close a sprint and move unfinished work
get_burndown	Sprint burndown (Scrum)

Releases

Tool	What it does
list_releases	Releases of a project with their readiness (not ready · ready with risks · ready), worked out from the board by fixed rules
get_release	One release: each feature's status with its reasons, the numbers and the gate result — agents report them as returned, never guess
move_to_release	Put an issue (or an epic with its children) into a release or take it out, with a reason — creating, gating and shipping a release are for people in the app

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

Project docs

Tool	What it does
list_docs	The project's brief, working notes, handoffs and the company brief, with what to read first (read_first)
get_docs_context	Everything to read before starting work, the template and its fields explained, as one Markdown text
get_doc	Read a doc (or an older version) with its current version
create_doc	Create a brief, working notes, or a handoff to teams or the whole project
update_doc	Edit a doc, or close/reopen a handoff — requires version
delete_doc	Delete a doc (restorable from its history) — requires version
get_doc_history	Every saved version: who saved it, through which agent, and when
restore_doc_version	Bring back an older version as a new one (history is kept)
acknowledge_handoff	Acknowledge a handoff addressed to you; the writer is told

Help from the BoardMark team

Tool	What it does
list_support_cases	Your company's support cases (every member sees them), newest activity first
get_support_summary	How many cases wait for you and how many are open
open_support_case	Open a case when the user needs help or hits a problem with BoardMark itself (not their project's issues) — text only
get_support_case	Read a case with its whole thread, including the BoardMark team's replies
reply_support_case	Reply in a case (text only; attachments on the web)
close_support_case	Close a case when the problem is solved
reopen_support_case	Reopen a closed case (within 30 days)
follow_support_case	Follow a case to get emails when the team answers
unfollow_support_case	Stop following a case

MCP resources

• board://{project_key}/project.md
• board://{project_key}/issues/{key}
• board://{project_key}/docs
• board://{project_key}/docs/{kind}/{slug}
• project_context (prompt)

* 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:

usersteamsseatspermissionsbillingcreating projectsproject settings & environmentsstarting sprintsimporting from Jiradeleting projects or the companymoving projects to another companydeleting accountsproject webhookstwo-step sign-in & signed-in devicesprofile pictures

How do I connect an AI agent to BoardMark?

Add BoardMark as an MCP server in your AI client (Claude Code, Codex, Gemini CLI, Cursor, VS Code and more), 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>. Setup for each client is on the MCP page (/mcp), or let the agent read the connect.md guide and set itself up.

Can AI agents follow our team's own workflow?

Yes. BoardMark has defaults for what each status means (for example In Review = QA is testing, Dev Done = waiting to be deployed for QA, Test Rejected = QA failed it) and for which part of the flow each role — developer, QA, BA — moves. If your team works differently, write company rules in the company brief and project rules in the project's brief or working notes. Agents always read those docs before they start and follow the most specific rule: the user's instruction > the project's docs > the company brief > the defaults. Your team writes its rules once, and every agent — Claude, ChatGPT, Codex, Cursor or any MCP client — works within the same agreed frame, more accurately, instead of being told again in every chat. Details: /docs/boards.

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 change an agent makes over MCP is recorded in the issue or doc history: whose rights it used, which AI client (the name you approved when connecting with sign-in, or the name you gave a personal access token), OAuth or token, which MCP tool made the call (for example update_issue), and a request id tying together everything one call changed. Issue history shows it as “via Claude Code”; cards and attachments changed or uploaded by an agent carry a badge, and the Agent & MCP page lists your agents' recent commits. Company admins can filter the Audit log to what was done through an AI agent, and requests BoardMark refused (no permission, or a rule) appear as “An AI agent was refused”.

Is there a rate limit?

Yes — 600 requests per minute per token by default.

Can I stop an AI agent from doing QA's job?

BoardMark warns it; it does not block. Every column has a lane — the role that works in that status (In Review = QA, for example) — and an agent gets a role on its token or on the approve screen when it connects. If a Developer agent moves In Review → Done, or skips the QA step, the move still happens but the agent gets a warning to stop, tell the user and hand off with a comment. Issue history shows the agent's role and a ⚠ on moves outside its lane. People are never warned or blocked.