MCP Connection

Breeks exposes agent access through a standalone MCP adapter. The MCP service is a thin adapter over Breeks API: it forwards every tool call to /api/agent/tools/{tool_name}, while the API resolves the organization from the project and still owns project isolation, actor permissions, tool-call logging, and audit logs. The adapter never reads or writes the database directly.

Local endpoint

Start the local stack, then connect to the MCP endpoint.

cp .env.example .env
docker compose up --build

URL: http://localhost:8767/mcp
Authorization: Bearer dev-mcp-token

Health check:

curl http://localhost:8767/healthz

Client config

Exact config keys vary by MCP client. The required values are Streamable HTTP transport, the MCP URL, and the bearer token.

{
  "mcpServers": {
    "breeks": {
      "type": "http",
      "url": "http://localhost:8767/mcp",
      "headers": {
        "Authorization": "Bearer dev-mcp-token"
      }
    }
  }
}

Tool envelope

Every Breeks MCP tool call carries project, actor, and input fields. The organization is resolved from the project server-side and is never a client parameter.

{
  "project_id": "project_tower",
  "actor": {
    "user_id": "user_site",
    "channel": "web"
  },
  "input": {}
}

MCP tools

The Breeks MCP adapter currently exposes 76 tools. Every tool name is prefixed with breeks. at the MCP boundary and is forwarded to the matching Breeks API tool contract without the prefix.

Use breeks.record.list and breeks.document.list to browse project content without a search query. Both return results, limit, offset, and has_more; limit defaults to 20 (maximum 50) and offset defaults to 0. To retrieve the next page, increase offset by limit while has_more is true.

List filters are top-level fields inside input. Record filters include record_type, status, priority, assigned_to, trade, tag, and tag_id. Document filters include document_type, status, folder_id, tag, tag_id, drawing metadata shorthands (trade, storey, document_subtype, author, revision), and custom for exact custom-field matches.

Records are ordered by creation time and documents by update time, newest first. Record lists contain published content and exclude private drafts and withdrawn records. Archived items are excluded unless explicitly filtered with status: "archived". Document lists omit deleted documents and show current drawings by default; request include_versions: true with document_type: "drawing" to include historical and pending revisions. Use the search tools for text and relevance matching, and the get tools to inspect an individual result.

Resources

breeks://projects/{project_id}/actors/{actor_user_id}/context
breeks://projects/{project_id}/actors/{actor_user_id}/records
breeks://projects/{project_id}/actors/{actor_user_id}/tasks
breeks://projects/{project_id}/actors/{actor_user_id}/documents
breeks://projects/{project_id}/actors/{actor_user_id}/members
breeks://projects/{project_id}/actors/{actor_user_id}/activity

Tokens

The MCP client authenticates with MCP_ACCESS_TOKEN. The MCP service uses AGENT_TOOL_SERVICE_TOKEN to call the API. Use long random values outside local development.

MCP_ACCESS_TOKEN=dev-mcp-token
AGENT_TOOL_SERVICE_TOKEN=dev-agent-tool-token

Retired annotation requests

Guided "Ask for markup" creation and the request_missing_drawing_information prompt have been removed from MCP. The breeks.document.get_annotation_request and breeks.document.revoke_annotation_request tools remain for authorized historical access; revocation requires confirm=true. New collaboration starts with Share. Existing tokens are not converted, and the old public request, image, and answer routes return 410 Gone.