Connect AI Assistants via MCP

Playbook ships an official MCP (Model Context Protocol) server that lets AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and any other MCP-aware client — read and modify your Playbook workspace using natural language. Ask the assistant to "find every approved logo on the Brand board," "tag these screenshots as mobile-onboarding," or "upload this batch of URLs to the Marketing board" and it will call the right Playbook API for you.

The server is built on top of the same v1 REST API documented in this site, so anything an MCP-connected agent can do, you can also do directly via HTTP — and vice versa.

How it works

AI assistant  ⇄  MCP client  ⇄  Playbook MCP server  ⇄  Playbook v1 REST API

MCP client advertises a list of "tools" exposed by the Playbook MCP server.
When the user asks a question, the assistant decides which tool to call, fills in the arguments, and the MCP client invokes the tool over JSON-RPC.
The Playbook MCP server translates each tool call into one or more authenticated requests against the Playbook v1 REST API.
The response is filtered (large/internal fields stripped) and returned to the assistant as text the model can reason about.

The server is hosted at https://mcp.playbook.com. Configure your MCP client with the URL and a Bearer token — no local install required.

Authentication

The MCP server authenticates to the Playbook API using your OAuth Bearer token, the same token described in Getting Started. Scopes:

read — required for every tool. Lets the assistant browse boards, assets, comments, documentation.
write — required for any mutation (uploads, moves, edits, deletes, comments, board changes).

Provide a token with only read scope if you want a strictly read-only assistant. The MCP server enforces scopes at the API layer — if the assistant tries to call a write tool with a read-only token, the request returns 403.

Never paste your token into a chat with the model. Configure it once in the MCP client config as an HTTP Authorization header. The assistant only ever sees tool names and arguments, never the token.

Client configuration

The Playbook MCP server speaks the streamable HTTP transport at https://mcp.playbook.com. Clients that support HTTP MCP natively (Claude Code, Cursor, ChatGPT) connect directly with a Bearer token in the Authorization header. Clients that only speak stdio (Claude Desktop) bridge through the mcp-remote npx shim — also covered below.

Claude Code

Add to .mcp.json at your project root, or to the global ~/.claude.json:

{
  "mcpServers": {
    "playbook": {
      "type": "http",
      "url": "https://mcp.playbook.com",
      "headers": {
        "Authorization": "Bearer your_bearer_token_here"
      }
    }
  }
}

Cursor

Settings → MCP → "Add new MCP server" and pick the HTTP transport. Use the same shape:

{
  "mcpServers": {
    "playbook": {
      "type": "http",
      "url": "https://mcp.playbook.com",
      "headers": {
        "Authorization": "Bearer your_bearer_token_here"
      }
    }
  }
}

ChatGPT

Use the "Custom Connector" flow in ChatGPT settings:

URL: https://mcp.playbook.com
Authentication: Bearer token (paste your Playbook OAuth token)

Claude Desktop

Claude Desktop currently only supports stdio MCP servers, so it bridges through the mcp-remote shim, which forwards stdio JSON-RPC to the hosted HTTP server. Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows:

{
  "mcpServers": {
    "playbook": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.playbook.com",
        "--header",
        "Authorization: Bearer your_bearer_token_here"
      ]
    }
  }
}

Available tools

All tools require the read scope. Tools marked write additionally require the write scope.

Read tools

Tool	What it does
`list_organizations`	List the workspaces the token has access to.
`list_boards`	List boards in a workspace, with optional search and hierarchy depth.
`get_board`	Fetch a single board's details by token.
`list_board_children`	List the direct child boards of a parent.
`list_assets`	List assets, optionally scoped to a board.
`get_asset`	Full details of one asset, including upload status (see Async ingest semantics).
`search_assets`	Keyword search across filename / title / tags.
`ai_search`	AI-powered visual and semantic search.
`get_comments`	Read comments on an asset or board.
`list_documentation`	Index the Playbook API docs and guides available to the assistant.
`read_documentation`	Read a specific docs page (e.g. `upload`, `webhooks`, `search`). Lets the assistant ground answers in the official docs without hallucinating.

Write tools — assets

Tool	What it does
`upload_from_url` `write`	Ingest a single asset by public URL. Returns immediately with a skeleton; Playbook fetches the bytes asynchronously.
`upload_from_urls` `write`	Ingest up to 100 assets in one call by public URL — all assets land on the same board, asynchronously.
`move_assets` `write`	Bulk-move up to 1000 assets to a target board.
`copy_assets` `write`	Bulk-copy up to 1000 assets to a target board (async).
`change_asset_tags` `write`	Add and/or remove tags on an asset.
`update_asset_status` `write`	Set an asset's status (e.g. `Approved`, `In Review`).
`update_asset` `write`	Update title, description, tags, status, or board for one asset.
`delete_asset` `write`	Soft-delete an asset (recoverable from trash).
`share_asset` `write`	Create or return the shareable link for one asset.

Write tools — boards

Tool	What it does
`create_board` `write`	Create a new board, optionally nested under a parent.
`update_board` `write`	Update a board's title, description, or parent.
`delete_board` `write`	Delete a board and all of its contents.
`share_board` `write`	Create or return the shareable link for a board.
`publish_board` `write`	Publish a board as a public page.

Write tools — comments

Tool	What it does
`create_comment` `write`	Post a top-level comment on an asset or board.

Async ingest semantics

The upload_from_url and upload_from_urls tools return immediately with skeleton assets — the asset rows exist but the bytes are still being fetched. The MCP response wraps each asset as { asset, status: "queued", note: "..." } to nudge the assistant against reporting the upload as "done" prematurely.

To detect completion, call get_asset on each returned asset token. The upload is finished when is_skeleton: false AND one of:

media_type populated → success
source_error non-null → failed (the message is the latest worker error)
is_link: true (only when as_link: true was passed) → kept as a bare link, no fetch attempted

See the Upload guide → Async Ingest Semantics for the same contract documented from the REST side, including recommended polling cadence.

Errors

Tool errors are returned as MCP isError: true text content with a human-readable message. The server maps Playbook API errors as follows:

Status	Tool message
401	"Authentication failed — check your Bearer token."
403	"Permission denied — check your token's scopes (`read`/`write`)."
404	"Not found — check the organization slug, board token, or asset token."
406	`"Invalid input: <message from the API>"` (used by batch URL ingest validation).
422	`"Validation error: <message from the API>"`.
429	"Rate limited — too many requests. Wait a moment and try again."
5xx	`"Playbook API error: <status> <statusText>"`.

Bearer tokens are never echoed back to the assistant, even when the upstream error body would contain one.

How it works​

Authentication​

Client configuration​

Claude Code​

Cursor​

ChatGPT​

Claude Desktop​

Available tools​

Read tools​

Write tools — assets​

Write tools — boards​

Write tools — comments​

Async ingest semantics​

Errors​