# BoardMark — guide for AI agents

Give this one link to any AI agent: it explains what BoardMark is, how the agent connects itself, and how to work on
the board. BoardMark is a project board (projects, issues, comments, sprints, project docs) stored as markdown files.
This MCP server lets an AI agent work on it with exactly the rights of the signed-in user. More about BoardMark: https://www.boardmark.ai — and the whole product, step by step, for any AI assistant (also without MCP): https://www.boardmark.ai/agents.md

- **MCP endpoint:** `https://mcp.boardmark.ai/mcp`
- **Transport:** Streamable HTTP, `POST` only, stateless, JSON responses (no SSE stream, no session id).
- **Server name to use in configs:** `boardmark`
- **Auth, option 1 — OAuth sign-in in the browser (recommended):** the client opens a BoardMark sign-in page, you pick the company and approve. Access is per company and revocable any time under *Signed-in apps* at https://app.boardmark.ai/agents.
- **Auth, option 2 — personal access token:** create a `board_pat_…` token at https://app.boardmark.ai/agents and send it as `Authorization: Bearer <token>`.
- **Role (optional, D136):** give the token — or the OAuth connection, on the approve screen — the role the agent works as (Developer, QA, BA, DevOps, Sales …). BoardMark then warns the agent (never blocks) when it moves an issue out of another role's lane. One token per role works well when one person runs several agents.

## What BoardMark is

- **An md-first issue board** for software teams, run by I C Develop Co., Ltd. People work in the web app (https://app.boardmark.ai); agents work through this MCP server. Both see the same data with the same permissions.
- **Everything is a markdown file.** One issue = one `.md` file with YAML frontmatter (`type`, `priority`, `severity` for bugs, `status`, `assignee`, `points`, `sprint`, `release`, `parent`, `links`, `labels`, `fields` (custom field values), `version`) and a markdown body; one comment = one file (`author`, `seq`, `version`, `updated_at`/`updated_by` once edited, `deleted` for a deleted one). Each project has a `project.md` with its board type, template, statuses, custom fields, saved filters and workflow. Every change is a commit with a new `version`; the server sets `created_by`/`created_at`/`updated_by`/`updated_at` itself (you never send them).
- **Companies → projects → issues.** A company has members; each project has a key (e.g. `KJ`) and its issues are `KJ-1`, `KJ-2`, … Issue types: `epic`, `task`, `subtask` (needs a parent) and `bug`. Issues carry a priority (`highest`, `high`, `medium` (default), `low`, `lowest`), story points, labels and links (`blocks`, `relates`, … — to issues of this or another project of the company, and `delivers` to a release `KEY/R-n`).
- **Three board types** (`board_type` in `get_project`):
  - `scrum` — a backlog and sprints; some projects run several sprints in parallel. A **person** starts each sprint.
  - `kanban` — continuous flow from a Backlog column, no sprints.
  - `pipeline` (Delivery pipeline) — no sprints; after development an issue passes *Testing (env)* → *Passed (env)* for each environment in order (for example develop, UAT, production), then Done. A failed test goes to *Test Rejected* and back to development.
- **Seven workflow templates** (`template` in `get_project`): Software delivery = `scrum`, `kanban`, `pipeline` (the board types, no extra fields); Business = `sales_billing`, `service_desk`, `budget_planning`, `roadmap_goals` — kanban boards with their own statuses, typed custom fields, saved filters and computed flags. See *Templates and custom fields* below.
- **Project docs** tell you why a project exists and where work stands: `brief` (goals and structure), `notes` (working notes: status, rules, gotchas), `handoffs` (work handed to a team or the whole project) and the read-only `company_brief`.
- **Roles.** In a project a user is `project_admin`, `member` or `viewer` (read-only); you have the role of the user who connected you. Company admins manage seats, members and billing in the web app — never through MCP.

## How to work in BoardMark

1. **Get your bearings.** "What's on my plate?" → `list_my_issues` (every project at once). "How are my projects doing?" → `list_projects` with `stats: true` (one call).
2. **Before you touch a project, read it.** A person may point you at a project with its link, `https://app.boardmark.ai/p/KEY` (clicking the project name on the board copies it): `KEY` is the project key. `get_project` gives the board type, the status ids, your role and `docs.read_first`; read those docs with `get_doc`, or call `get_docs_context` for everything in one text. Acknowledge handoffs addressed to you (`acknowledge_handoff`) once read.
3. **Read before you write.** Every write takes the `version` of your latest read (`get_issue` before `update_issue`). On `409 version_conflict` the error carries the current file: re-read, re-apply your change on top, retry. Never overwrite someone else's change blindly — ask the user when the changes disagree.
4. **One edit, one call.** `update_issue` changes any number of fields at once; do not split an edit into several calls.
5. **Use the project's statuses.** Take status ids from `get_project`, never guess them; what they mean and who moves what is in *Default workflow* below, unless the project's docs or the column's own `meaning` say otherwise. A WIP limit (`wip_limits`) is a warning, not a block; never move an issue into a column marked `removing: true` (it is being deleted). On a scrum board you change statuses only for issues in a sprint a person has started (otherwise `409 sprint_not_started`): plan in the backlog and ask the user to press *Start sprint*. On a pipeline board, "deployed to UAT" means the `testing_<id>` status of that environment.
6. **Plan and track.** `create_issue` (no `sprint` = backlog), `move_to_sprint`, `rank_issue` (exactly one of `before` / `after`), `list_sprints`, `get_burndown`. On projects with Releases on (any board type): `list_releases` / `get_release` (readiness worked out from the board — report it as returned, never guess) and `move_to_release` (an epic brings its children); creating, gating and shipping a release is for people in the web app.
7. **Talk and attach.** `add_comment` (replies with a parent comment); `update_comment` / `delete_comment` take the comment's `version` from `list_comments` — only the author edits, a delete leaves a "deleted" tombstone so replies stay. Files: `request_upload` → PUT the bytes → `attach_file`; to show an image inline, write `![name](path)` with the returned `path` in the comment or issue body (never base64); read files back with `list_attachments` + `get_download_url`; `delete_attachment` removes a file for good — only files your token uploaded, and only after the user says yes.
8. **Keep the docs current.** `update_doc` takes the complete markdown body and the `version` from `get_doc`. Undo a bad edit with `get_doc_history` + `restore_doc_version` — never delete to fix it.
   Colour and highlighter (optional, use sparingly; markdown stays the main format) work in issue descriptions, comments and docs as inline HTML: `<mark>text</mark>` highlights (yellow; or `<mark data-color="green">`) and `<span data-color="red">text</span>` colours text. Colours: yellow, green, red, blue, purple — e.g. green = passed / expected result, red = must fix / bug / actual result, blue = note, purple = question to confirm. Any other HTML is shown as plain text; keep the opening and closing tag in the same paragraph.
9. **Stay inside the user's intent.** Delete only when asked. Everything you write is recorded with your agent token, your client's name (e.g. "Claude Code") and the tool you called (`get_history` → `agent`), badged "via …" in the app; refused calls land in the company audit log.
10. **Web only:** creating, deleting and restoring projects (and choosing their template), moving a project to another company (transfer key), project settings, the Timeline set-up, environments, board columns, custom field definitions, saved filters, members, seats, billing, deleting a company, deleting a user account, and starting sprints. There are no tools for these — tell the user to do them in the web app (https://app.boardmark.ai).

## Templates and custom fields

- **Templates.** A project is created from one of seven templates (`template` in `get_project`; older projects: the board type). *Software delivery:* `scrum`, `kanban`, `pipeline` — the boards above, no extra fields. *Business* (kanban, every plan): `sales_billing` — deals and their installments (Draft → Sent → Signed → In delivery → Billing → Closed, plus Lost); `service_desk` — requests with requester, category, urgency, SLA due and channel (New → Triage → In progress → Waiting → Done); `budget_planning` — budget lines with planned, actual, remaining (= planned − actual, computed), owner, quarter, cost center, vendor (Proposed → Approved → Spending → Closed, plus Rejected); `roadmap_goals` — goals on a Timeline (Idea → Planned → In progress → Done, plus Dropped = done but not a success), see *Roadmap & Goals* below. There are no new issue types: a deal, request, budget line or goal is a `task`; an installment is a `subtask` whose `parent` is the deal; a key result is a `subtask` of its goal.
- **Custom fields.** `get_project` → `fields` defines them: `id` (the key), `name`, `type` (`text`, `number`, `money` — 2 decimals in `template_settings.currency` —, `date` `YYYY-MM-DD`, `person` = user id, `select` = one of `options`, `url`, `customer` = free text, `formula` and `rollup` = read-only, returned in `computed`), `types` (which issue types take it), `required`. Values live in the issue's `fields` object: `create_issue` and `update_issue` take `fields` and merge it key by key (clear a value the way `update_issue` clears `assignee`: send the key with no value); `write_file` checks it the same way. Errors: `400 unknown_field`, `400 invalid_field_value` (wrong type, option, date — or a required field missing on create), `400 formula_readonly`. Field definitions and saved filters are changed in the web app (fields beyond the template: Premium).
- **Flags and filters.** Board-core computes flags from the fields and today (Asia/Bangkok), never stores them: `overdue`, `due_soon`, `bill_due`, `awaiting_signature`, `all_paid` (Sales & Billing), `sla_soon`, `sla_over` (Service desk), `over_budget`, `spent_warn` (Budget planning), `on_track`, `at_risk`, `off_track` (Roadmap & Goals). Filter with `search_issues` `flag` (e.g. `flag: ["overdue"]`), by field with `fields` — a JSON string of `[{id, op, value}]` (`eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `between`, `in`, `empty`, `not_empty`; `today` / `me`) — and sort with `sort_field` + `sort_dir`. Every issue comes back with `fields`, `flags`, `computed` and, for a deal, `children` (count, done, amount_total, paid_total, paid_count). The project's `saved_filters` are ready-made `search_issues` queries. `get_docs_context` explains the project's template and fields in words.
- **Installments.** In Sales & Billing an installment is a `subtask` of the deal with `amount`, `bill_on`, `due_on` and later `invoiced_at` / `invoice_no` / `paid_at` / `paid_amount`; its state Not yet → Invoiced → Paid is derived from those dates, not from `status`. "Paid" = `update_issue` with `fields: {"paid_at": "YYYY-MM-DD", "paid_amount": <amount>}`. Deleting a deal deletes its installments. `list_my_issues` includes the installments of deals you own.
- **Example — "ดีลไหนค้างชำระ / which deals are unpaid?"** → `search_issues` with `{"project_key": "KEY", "flag": ["overdue"]}`: each result is an installment, its `parent` is the deal (read the deal's `fields.customer` and `children.paid_total` to answer). For everything not collected yet, whether invoiced or not: `{"project_key": "KEY", "type": ["subtask"], "fields": "[{\"id\":\"paid_at\",\"op\":\"empty\"}]"}`.
- **Cross-project links and releases.** A link's `id` may be an issue key of another project of the same company (`link_issues`, `update_issue` `links`) — you must be able to open both projects, else `403 link_target_forbidden`; board-core writes the inverse link in the other project. `delivers` points at a release instead: `id` = `KEY/R-n` (`list_releases` of that project), must exist (`404 release_not_found`), no inverse. `get_issue` resolves every link live in `linked[]` (issue: title, status, category; release: state, progress %; `readable: false` = a project you cannot open or a target that is gone — only the key is known). `search_issues` `linked_to: "KJ-120"` or `"NW/R-3"` lists the issues that link to that target. `get_docs_context` adds a "linked projects" line when a project links out.
- **Rollup fields and RICE.** A `rollup` field (`get_project` `fields`, `rollup: {from: links | children, link_types?, fn: progress | count | sum | min_date | max_date, field?}`) is computed at read time over the issue's readable link targets or its subtasks and returned in `computed` — `progress` = mean progress (done issue = 100, release = % past its last gate), `count`, or `sum` / `min_date` / `max_date` of a target field; depth 1. A formula may be `{fn: rice, of: [reach, impact, confidence, effort]}` = reach × impact × confidence ÷ effort (1 decimal). Both are read-only (`400 formula_readonly`). Template rollups work on every plan; adding your own rollup fields or setting up the Timeline for another template is Premium, in the web app.
- **Roadmap & Goals and the Timeline.** `roadmap_goals`: a goal is a `task` with `quarter` (Q1–Q4), `start` + `end` (required dates), `owner`, RICE inputs `reach` / `impact` / `confidence` / `effort`, computed `score` (RICE), `progress` (rollup over its `relates` / `blocks` / `delivers` links) and `linked` (count); link a goal to the issues and releases that deliver it. Flags: `off_track` (past `end`, progress < 100), `at_risk` (elapsed % − progress % > 25 before `end`), `on_track` (the rest); none when done or without dates; owners get one bell item when a goal goes off track. The project's `timeline: {start, end, progress}` drives the web app's Timeline layout (bars start → end filled by progress); through MCP you move a goal by writing `fields.start` / `fields.end`. Saved filters: Off track, At risk, This quarter (`quarter eq current` = the current Bangkok quarter), Mine. Sales & Billing deals get a `delivery_progress` rollup over their `delivers` / `relates` links to the dev project.
- **Example — "เป้าหมาย Q4 ไหนล่าช้า / which Q4 goals are late?"** → `search_issues` with `{"project_key": "KEY", "flag": ["off_track"], "fields": "[{\"id\":\"quarter\",\"op\":\"eq\",\"value\":\"Q4\"}]"}`; for each goal read `fields.end`, `computed.progress` and `fields.owner` (name via `list_people`), then `get_issue` → `linked[]` to say which linked issue or release is holding it back.

## Default workflow and what each status means

These are BoardMark's loose default rules. The user's instruction wins; then the project's docs (brief, working notes); then the company brief; then these defaults. A project with its own statuses (e.g. imported from Jira) explains them in its docs — if a status is not explained anywhere, infer from its name and category and ask the user when it matters.

| Status | id | Boards | Means | Who moves an issue here | Lane (D136) |
|---|---|---|---|---|---|
| Backlog | `backlog` | kanban, pipeline | Not planned yet; ideas and requests being written and refined. | anyone — a BA writes and refines issues here | BA |
| On Hold | `on_hold` | kanban, pipeline (when switched on) | Paused — waiting for the customer, a decision or another team. | anyone, with a comment saying what it waits for | — |
| To Do | `todo` | all | Ready to be worked on; waiting for someone to pick it up. | whoever plans the work (BA, lead) | Developer |
| In Progress | `in_progress` | scrum, kanban | A developer is working on it. | the developer, when starting | Developer |
| Developing | `developing` | pipeline | A developer is working on it. | the developer, when starting | Developer |
| In Review | `in_review` | scrum, kanban | Development is finished and handed to QA; QA is testing it. | the developer, when done | QA |
| Dev Done | `dev_done` | pipeline | Development is finished; waiting to be deployed to the first environment (e.g. develop) for QA. | the developer, when done | DevOps |
| Testing (env) | `testing_<env>` | pipeline | Deployed to that environment; QA is testing it there. | whoever deploys it there, or QA when they start | QA |
| Passed (env) | `passed_<env>` | pipeline | Passed QA on that environment; waiting to be deployed to the next environment. | QA | DevOps |
| Test Rejected | `test_rejected` | all | QA tested it and it failed; it goes back to the developer, who moves it to In Progress / Developing when they resume. | QA, with a comment: steps, expected, actual | Developer |
| Done | `done` | all | Finished — passed QA (on a pipeline: passed the last environment). | QA | — |

Roles:

- Work in your role only — the user tells you (developer, QA, BA, DevOps, …); else the role set on your token (Agents page, or when the OAuth client was connected); if neither is clear, ask once. BoardMark connects agents in every role.
- Lanes (spec D136): every status belongs to the role that works on it and moves it on — by default Backlog BA; To Do, In Progress / Developing, Test Rejected Developer; In Review, Testing (env) QA; Dev Done, Passed (env) DevOps; a project admin can change them in the column editor. Move issues only out of your own lane. If a transition_issue / update_issue result carries `warnings`, the move was done but stepped into another role's work: stop, tell the user and hand off with a comment (or undo it). Pass `as_role` with the move when the user told you your role. Warnings never block.
- Developer: pick issues assigned to you first (list_my_issues, or search_issues assignee=me in the running sprint), then unassigned To Do issues — assign yourself before you start; never take an issue assigned to someone else unless the user asks. Move it To Do → In Progress (Developing on a pipeline) when you start, and → In Review (Dev Done on a pipeline) with a short summary comment when you finish. A Test Rejected issue goes back to In Progress / Developing when you resume it.
- QA: test issues in In Review (scrum, kanban) or Testing (env) (pipeline). Passed → Done, or Passed (env) on a pipeline (Done after the last environment). Failed → Test Rejected, with a comment: steps, expected, actual.
- BA: write and refine issues — description, acceptance criteria, type, priority, points, links, parent — in Backlog / To Do. Do not move issues past To Do.
- Deploying: moving Dev Done → Testing (env), or Passed (env) → Testing (next env), means the build is on that environment — do it when you deployed it or the user says it is there.

**Writing your own rules:** a company admin puts company-wide rules in the company brief (admin console); a project keeps its own in its brief or working notes (gear on the board → Docs), for example a `## Workflow rules` section with the team's statuses, who moves what and when. Agents read the company brief first, then the project docs, and follow the most specific rule.

## For AI agents: set yourself up

Follow these steps without asking the user more than needed.

1. Detect which client you are running in (Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code, …) and jump to its section below. Unknown client → *Any other client* / *Generic*.
2. Prefer OAuth when your client supports it: add the server without a token, run the login command, and ask the user to finish sign-in in the browser window that opens.
3. Otherwise ask the user to create a personal access token at https://app.boardmark.ai/agents and put it in an environment variable `BOARDMARK_TOKEN` (for example in their shell profile). Avoid asking them to paste the token into the chat; never write a token into a file that is committed to git.
4. Write the configuration from the section, using the server name `boardmark` and the URL `https://mcp.boardmark.ai/mcp`.
5. Verify: list the tools (expect `list_projects`, `get_issue`, …) and call `list_projects`.
6. Before working on a project, read its docs: `get_project` → read each doc in `docs.read_first` with `get_doc`, or call `get_docs_context` for everything in one text.

## Claude Code

OAuth:

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

Then start Claude Code, run `/mcp`, pick `boardmark` → Authenticate, and finish sign-in in the browser.

Token:

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

Project file `.mcp.json`:

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

## Claude Desktop and claude.ai (web, mobile)

1. Customize › Connectors › Add custom connector.
2. URL: `https://mcp.boardmark.ai/mcp`
3. Connect and sign in (OAuth). For the client identity, "Use Claude's published identity" and "Register automatically" both work.

Team / Enterprise: an Owner adds the connector under Organization settings › Connectors; members then connect and sign in.
Token instead of OAuth (only where "Request headers" is available): header `authorization` = `Bearer <token>`.

## OpenAI Codex (CLI, desktop app, IDE)

Codex app (and ChatGPT desktop): Settings › MCP servers › Add server › Streamable HTTP, URL `https://mcp.boardmark.ai/mcp`, Save, Restart, then Authenticate to sign in. The app, CLI and IDE extension share `~/.codex/config.toml`, so adding it once is enough.

CLI with OAuth:

```bash
codex mcp add boardmark --url https://mcp.boardmark.ai/mcp
codex mcp login boardmark
```

Token:

```bash
codex mcp add boardmark --url https://mcp.boardmark.ai/mcp --bearer-token-env-var BOARDMARK_TOKEN
```

`~/.codex/config.toml`:

```toml
[mcp_servers.boardmark]
url = "https://mcp.boardmark.ai/mcp"
bearer_token_env_var = "BOARDMARK_TOKEN"
```

## ChatGPT (web)

Plus, Pro, Business, Enterprise and Edu plans:

1. Settings › Security and login › turn on Developer mode.
2. Add an app / connector with the URL `https://mcp.boardmark.ai/mcp` and choose OAuth.
3. Sign in to BoardMark in the window that opens.

## Google Antigravity

`~/.gemini/config/mcp_config.json` (or `.agents/mcp_config.json` in the workspace). Note the key is `serverUrl`:

```json
{"mcpServers":{"boardmark":{"serverUrl":"https://mcp.boardmark.ai/mcp"}}}
```

Sign in via the MCP panel (`/mcp`). Token instead of OAuth: add `"headers":{"Authorization":"Bearer <token>"}` next to `serverUrl`.

## Gemini CLI

OAuth:

```bash
gemini mcp add --transport http boardmark https://mcp.boardmark.ai/mcp
```

Then run `/mcp auth boardmark` inside Gemini CLI.

Token:

```bash
gemini mcp add --transport http -H "Authorization: Bearer $BOARDMARK_TOKEN" boardmark https://mcp.boardmark.ai/mcp
```

`settings.json`:

```json
{"mcpServers":{"boardmark":{"httpUrl":"https://mcp.boardmark.ai/mcp","headers":{"Authorization":"Bearer $BOARDMARK_TOKEN"}}}}
```

## xAI (API, Grok Build CLI, grok.com)

xAI API (Responses), remote MCP tool — token only:

```json
{"type":"mcp","server_url":"https://mcp.boardmark.ai/mcp","server_label":"boardmark","authorization":"<token>"}
```

Grok Build CLI (browser sign-in on first use):

```bash
grok mcp add --transport http boardmark https://mcp.boardmark.ai/mcp
```

Approve once: when the tab says "Authorization complete", close it. Grok's sign-in listener stops after that, so a later `127.0.0.1 refused to connect` tab is harmless — don't approve again. Check with `grok mcp doctor boardmark` (`grok mcp list` doesn't show sign-in state).

With a token:

```bash
grok mcp add --transport http boardmark https://mcp.boardmark.ai/mcp --header 'Authorization: Bearer ${BOARDMARK_TOKEN}'
```

grok.com: grok.com/connectors › New connector › Custom › URL `https://mcp.boardmark.ai/mcp`.

## Goose

`goose configure` › Add Extension › Remote Extension (Streamable HTTP) › URL `https://mcp.boardmark.ai/mcp` — OAuth starts automatically.

`~/.config/goose/config.yaml`:

```yaml
extensions:
  boardmark:
    name: BoardMark
    type: streamable_http
    uri: https://mcp.boardmark.ai/mcp
    enabled: true
    timeout: 300
    # token instead of OAuth:
    # headers:
    #   Authorization: "Bearer <token>"
```

## OpenCode

`opencode.json`:

```json
{"$schema":"https://opencode.ai/config.json","mcp":{"boardmark":{"type":"remote","url":"https://mcp.boardmark.ai/mcp"}}}
```

Then `opencode mcp auth boardmark`. Token instead of OAuth — add to the `boardmark` entry:

```json
"headers":{"Authorization":"Bearer {env:BOARDMARK_TOKEN}"},"oauth":false
```

## Cursor

`mcp.json` (`~/.cursor/mcp.json` or `.cursor/mcp.json`):

```json
{"mcpServers":{"boardmark":{"url":"https://mcp.boardmark.ai/mcp"}}}
```

Cursor offers the OAuth sign-in. Token instead: add `"headers":{"Authorization":"Bearer ${env:BOARDMARK_TOKEN}"}` next to `url`.

## VS Code (GitHub Copilot)

`.vscode/mcp.json` — OAuth starts automatically:

```json
{"servers":{"boardmark":{"type":"http","url":"https://mcp.boardmark.ai/mcp"}}}
```

Token (VS Code prompts for it once and stores it securely):

```json
{"inputs":[{"type":"promptString","id":"boardmark-token","description":"BoardMark token","password":true}],"servers":{"boardmark":{"type":"http","url":"https://mcp.boardmark.ai/mcp","headers":{"Authorization":"Bearer ${input:boardmark-token}"}}}}
```

## Windsurf / Devin Desktop

`mcp_config.json`:

```json
{"mcpServers":{"boardmark":{"serverUrl":"https://mcp.boardmark.ai/mcp","headers":{"Authorization":"Bearer ${env:BOARDMARK_TOKEN}"}}}}
```

## Kiro

`.kiro/settings/mcp.json` (OAuth):

```json
{"mcpServers":{"boardmark":{"url":"https://mcp.boardmark.ai/mcp"}}}
```

Token instead: add `"headers":{"Authorization":"Bearer ${BOARDMARK_TOKEN}"}` next to `url`.

## Zed

Zed `settings.json` — OAuth is used when no `Authorization` header is set:

```json
{"context_servers":{"boardmark":{"url":"https://mcp.boardmark.ai/mcp"}}}
```

Token instead: add `"headers":{"Authorization":"Bearer <token>"}` next to `url`.

## Cline

MCP settings (token):

```json
{"mcpServers":{"boardmark":{"type":"streamableHttp","url":"https://mcp.boardmark.ai/mcp","headers":{"Authorization":"Bearer <token>"}}}}
```

## Continue

`config.yaml` (token):

```yaml
mcpServers:
  - name: boardmark
    type: streamable-http
    url: https://mcp.boardmark.ai/mcp
    requestOptions:
      headers:
        Authorization: "Bearer <token>"
```

## LM Studio

`mcp.json` (token):

```json
{"mcpServers":{"boardmark":{"url":"https://mcp.boardmark.ai/mcp","headers":{"Authorization":"Bearer <token>"}}}}
```

## Mistral Le Chat

An admin adds it: Connectors › Add Connector › Custom MCP Connector › URL `https://mcp.boardmark.ai/mcp`. OAuth is detected automatically (or choose a Bearer token).

## Microsoft Copilot Studio

Tools › Add a tool › New tool › Model Context Protocol:

- Server URL: `https://mcp.boardmark.ai/mcp`
- Authentication: OAuth 2.0 › Dynamic discovery (recommended), or API key in header `Authorization` with value `Bearer <token>`.

## Any other client (stdio only)

Bridge with `mcp-remote`. Token (no space after the colon in `Authorization:${AUTH_HEADER}`):

```bash
export AUTH_HEADER="Bearer $BOARDMARK_TOKEN"
npx -y mcp-remote@latest https://mcp.boardmark.ai/mcp --header "Authorization:${AUTH_HEADER}"
```

Leave out `--header` to sign in via OAuth in the browser instead. JSON form for clients that start stdio servers:

```json
{"mcpServers":{"boardmark":{"command":"npx","args":["-y","mcp-remote@latest","https://mcp.boardmark.ai/mcp","--header","Authorization:${AUTH_HEADER}"],"env":{"AUTH_HEADER":"Bearer <token>"}}}}
```

## Generic

Any MCP client that supports Streamable HTTP and either:

- OAuth 2.1 — discovery at `https://mcp.boardmark.ai/.well-known/oauth-protected-resource` (RFC 9728); Dynamic Client Registration and Client ID Metadata Documents are both supported; PKCE S256; resource `https://mcp.boardmark.ai/mcp`; scope `board`; or
- a static header `Authorization: Bearer <token>`.

## What you can do

- **Projects and issues:** list projects (with `stats: true` for an overview), search (filter and sort by `priority`, by custom `fields`, by template `flag`, by `linked_to`), read (links resolved live in `linked[]`, rollups in `computed`), create and update issues (custom `fields` included), link issues across the company's projects and to releases (`link_issues`), transitions, ranking, "my work" (`list_my_issues`).
- **Comments and sprints:** comments with replies and @mentions (`[@Name](mention:usr_…)` — ids and names from `list_people`, who can open the project), edit or delete your own; watch issues (`watch_issue`); plan, start and close sprints; burndown.
- **Project docs:** brief, working notes, handoffs and the company brief — `list_docs`, `get_doc`, `update_doc`, `get_docs_context`, `acknowledge_handoff`. Read them before working on a project.
- **History:** every write is recorded with your agent token, client name, tool and request id (`get_history` → `agent`); refused calls (403, 409 `sprint_not_started`) are in the company audit log.
- **Help from the BoardMark team:** open a support case about a problem with BoardMark itself (not your project's issues), check its status and read and answer the team's replies (`list_support_cases`, `open_support_case`, `get_support_case`, `reply_support_case`); every member of the company sees the case; text only — files are attached in the web app (Help → Contact support).
- **Resources:** `board://{project_key}/project.md`, `board://{project_key}/issues/{issue_key}`, `board://{project_key}/docs`, `board://{project_key}/docs/{kind}/{slug}`.
- **Prompt:** `project_context` (argument `project_key`) — the project's docs as one message.

You never get more rights than the user: creating, deleting or moving projects, project settings, members, billing, deleting a company and deleting an account are web only.

## Troubleshooting

- **401 Unauthorized:** sign in again (OAuth), or the token expired or was revoked — create a new one at https://app.boardmark.ai/agents.
- **403 Forbidden:** your role in that project does not allow the action; ask a project admin.
- **406 Not Acceptable:** no longer returned — clients that send only `Accept: application/json` work.
- **Wrong company:** tokens and OAuth grants are per company; sign in or create a token for the other company.
- **Revoke access:** personal access tokens and signed-in apps at https://app.boardmark.ai/agents.

Last updated: 2026-10-07