Hashboard MCP Server: Connect AI Agents with 54 Tools

Hashboard ships a Model Context Protocol server at /mcp that exposes the full product surface — boards, cards, documents, attachments, comments, labels, search, and admin operations — as 54 callable tools. Any MCP-compatible AI client can connect with a single bearer token and immediately read, write, and navigate a Hashboard instance with the same fidelity as the REST API or the browser UI.

Endpoint and transport

The MCP server listens at POST /mcp. It uses the @modelcontextprotocol/sdk’s WebStandardStreamableHTTPServerTransport with enableJsonResponse: true, making every exchange a single HTTP request/response pair — no persistent connection, no SSE stream. Stateless by design. Each POST creates a fresh McpServer instance bound to the authenticated actor. There is no session to resume or delete; GET /mcp and DELETE /mcp both return 405 with a plain explanation. This keeps the server compatible with the synchronous service layer (no await can interleave inside a transaction) and eliminates state management entirely.

Authentication

Authentication is a single Authorization: Bearer hb_… header — the same token used for every REST call. The SvelteKit hooks.server.ts gate resolves the actor before the MCP route runs, so the tool implementations receive a fully authenticated principal and never need to inspect credentials themselves. An MCP session acts as the agent, not as its owner. Every tool call is attributed to the agent’s own identity in activity feeds, card histories, and comments.

There is no OAuth flow for the MCP server. Tokens are issued via POST /api/v1/tokens on the REST API (see Agent Management). Add an OAuth layer only if a specific connector UI — such as claude.ai’s — requires it.

Connecting an MCP client

The configuration below works with Claude Desktop and any other client that supports streamable HTTP transport:

{
  "mcpServers": {
    "hashboard": {
      "transport": "http",
      "url": "https://hashboard.example.com/mcp",
      "headers": {
        "Authorization": "Bearer hb_YOUR_AGENT_TOKEN"
      }
    }
  }
}

Replace https://hashboard.example.com with your instance’s origin and hb_YOUR_AGENT_TOKEN with a token issued to your agent principal.

How read tools work

get_board, get_card, and get_doc return the same markdown rendition served at /<type>/<id>.md. The response opens with YAML frontmatter carrying all IDs and the doc version field needed for save_doc. Every link in the body uses the .md suffix so follow-up fetches need no Accept header. This means an agent navigating the workspace sees one consistent format across direct URL fetches and MCP tool calls.

Error handling

Service errors are translated into MCP tool errors the model can read and react to:

ConflictError (optimistic concurrency on doc saves) returns isError: true with the message and the currentVersion value so the agent can re-read and retry.
All other ServiceError subtypes (NotFoundError, ForbiddenError, ValidationError, etc.) return isError: true with the error message.
Unexpected errors are re-thrown and surface as uncaught exceptions rather than being swallowed silently.

All 54 tools

The credential and identity lifecycle — token creation/revocation, agent creation, and agent deactivation — is deliberately absent from MCP. Fresh secrets must never transit an LLM context. These operations are REST-only. The exact tool count is asserted in server.spec.ts; adding a tool requires updating that assertion.

Identity (1 tool)

Tool	Description
`whoami`	Returns your principal ID, kind (`human` or `agent`), display name, and either your role (humans) or your owner’s ID (agents). Use this to confirm which identity the current token resolves to.

Boards (7 tools)

Tool	Description
`list_boards`	List boards visible to you — name, ID, visibility, and URL. Pass `archived: true` to list archived boards instead.
`get_board`	Full board as markdown: columns with their cards, each linked as `/cards/<id>`. Frontmatter carries the board ID and metadata.
`create_board`	Create a board with a name, optional description, and visibility (`private` by default). Board grants cascade to cards and their docs.
`update_board`	Update a board’s name, description (pass `null` to clear), or visibility. Visibility changes are creator-only.
`archive_board`	Archive a board (creator-only).
`unarchive_board`	Restore an archived board (creator-only).
`get_board_archive`	Returns the archived columns and cards for a board — the IDs `unarchive_column` and `unarchive_card` need.

Columns (6 tools)

Tool	Description
`list_columns`	List the columns of a board in position order.
`create_column`	Add a column at the end of a board.
`rename_column`	Rename a column.
`move_column`	Reorder a column by specifying `prevId` and/or `nextId` neighbor IDs. Omit both to move to the end.
`archive_column`	Archive a column (board-creator-only). Its ID remains discoverable via `get_board_archive`.
`unarchive_column`	Restore an archived column (board-creator-only).

Cards (10 tools)

Tool	Description
`get_card`	Full card as markdown: frontmatter with IDs, doc version, labels, assignees, linked docs, and attachment URLs; description; linked documents; attachments; comments.
`create_card`	Create a card. Provide `columnId` to place it on a board, or omit it for a loose (inbox) card. `content` is the full-markdown description; `dueAt` is ISO 8601.
`update_card`	Update card fields: `title`, `dueAt` (ISO 8601 or `null` to clear), `visibility`. Content edits go through `save_doc`.
`move_card`	Place a card in a column between `prevId`/`nextId` neighbors. Omit both to append at the end.
`detach_card`	Remove a card from its board entirely; it becomes a loose card.
`archive_card`	Archive a card (creator-only).
`unarchive_card`	Restore an archived card (creator-only).
`assign_card`	Assign a principal (human or agent) to a card. Reserved for the card’s creator and current assignees. Assigning a private card shares it with the assignee durably.
`unassign_card`	Remove a principal from a card’s assignee list.
`inbox`	Your household’s loose cards — created by or assigned to you or your agents. Pass `archived: true` for archived loose cards.

Documents (7 tools)

Tool	Description
`list_docs`	List standalone documents visible to you. Optionally filter by `boardId`.
`get_doc`	A document as markdown with frontmatter. `version` is the `baseVersion` for `save_doc`; `linked_cards` lists cards referencing it.
`create_doc`	Create a standalone markdown document, optionally filed under a board.
`save_doc`	Save a document (card descriptions included — use the `docId` from `get_card` frontmatter). `baseVersion` must match the version you read; a conflict returns `currentVersion` to retry with.
`delete_doc`	Permanently delete a standalone document (creator-only). Card description docs cannot be deleted — archive the card instead.
`set_doc_visibility`	Change a standalone document’s visibility (creator-only). Card descriptions inherit their card’s visibility and cannot be changed here.
`list_revisions`	A document’s content snapshots, newest first: version, author ID, timestamp, and character count. Does not include content bodies.

Links (2 tools)

Tool	Description
`link_doc_to_card`	Link a standalone document to a card (a reference, not ownership). Requires write on both the card and the doc; idempotent.
`unlink_doc_from_card`	Remove a document link from a card.

Attachments (3 tools)

Tool	Description
`list_attachments`	Files attached to exactly one card or standalone document. Pass exactly one of `cardId` or `docId`. Each file is served at `/attachments/<id>`.
`attach_file`	Attach a file to a card or standalone document with its content base64-encoded. See the note below about size limits.
`delete_attachment`	Remove an attached file. Allowed for the uploader’s household or the subject’s creator (moderation).

MCP uploads use base64-encoded content in a single message, which keeps the entire payload in the conversation context. This path has a smaller size cap than the REST binary upload endpoint. For larger files, POST the raw bytes to /api/v1/cards/<id>/attachments?filename=NAME or /api/v1/docs/<id>/attachments?filename=NAME with Content-Type: application/octet-stream. Do not use multipart/form-data — SvelteKit rejects cross-site form submissions before the route runs.

Comments (2 tools)

Tool	Description
`add_comment`	Comment on exactly one of a card or a document. Pass exactly one of `cardId` or `docId`.
`delete_comment`	Delete a comment — allowed for the author’s household or the creator of the card/document (moderation).

Labels (6 tools)

Tool	Description
`list_labels`	The global label palette: names, IDs, and colors.
`create_label`	Add a label to the global palette. Names are unique instance-wide.
`update_label`	Rename or recolor a palette label; the change applies everywhere the label is used.
`delete_label`	Delete a palette label, detaching it from every card.
`add_label_to_card`	Attach a label from the global palette to a card.
`remove_label_from_card`	Detach a label from a card (the label itself stays in the palette).

Directory (1 tool)

Tool	Description
`list_principals`	Workspace directory: all non-disabled humans and agents, useful for finding principal IDs to pass to `assign_card`. Includes the synthetic Guest principal (anonymous link visitors) — it cannot be assigned.

Search (1 tool)

Tool	Description
`search`	Substring search over board names/descriptions, card titles/descriptions, and standalone document titles/content. Visibility-filtered; minimum 2 characters. Results grouped by boards, cards, and documents.

Activity (1 tool)

Tool	Description
`get_activity`	Activity feed for exactly one of a board, card, or document, newest first. Pass exactly one of `boardId`, `cardId`, or `docId`. Default 50 events, max 200.

Settings & Admin (7 tools)

These tools require the admin or super role on the acting principal (agents inherit their owner’s role).

Tool	Description
`admin_get_settings`	Instance settings: local registration toggle and invite-only mode.
`admin_update_settings`	Toggle local registration (`registrationEnabled`) and invite-only mode (`inviteOnly`).
`admin_list_users`	Every principal with role, kind, and sign-in methods (local username / OIDC).
`admin_set_role`	Set a human’s instance role (`user` or `admin`). The superadmin cannot be modified, and `super` cannot be granted via the API.
`admin_list_invites`	Registration invites and their usage. Raw codes are never stored — this returns hashes and metadata only.
`admin_create_invite`	Create a single-use invite code, optionally with an ISO 8601 expiry. The code is returned exactly once.
`admin_delete_invite`	Revoke an unused invite. Used invites remain as an audit trail.

Get Started

Deployment

Core Concepts

Authentication

AI Agents & MCP

Hashboard MCP Server: Connect AI Agents with 54 Tools

Endpoint and transport

Authentication

Connecting an MCP client

How read tools work

Error handling

All 54 tools

Build docs developers (and LLMs) love

Get Started

Deployment

Core Concepts

Authentication

AI Agents & MCP

Documentation Index

​Endpoint and transport

​Authentication

​Connecting an MCP client

​How read tools work

​Error handling

​All 54 tools

Build docs developers (and LLMs) love

Endpoint and transport

Authentication

Connecting an MCP client

How read tools work

Error handling

All 54 tools