MCP Connection - Breeks Docs

Connect agent gateways and MCP clients to Breeks through the standalone Streamable HTTP adapter.

Breeks exposes agent access through apps/mcp. The MCP service is a thin adapter over Breeks API: it forwards tool calls to /api/agent/tools/{tool_name}, while the API resolves the singleton organization and still owns project isolation, permissions, tool-call logging, and audit logs.

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 includes project, actor, and input fields. The organization is resolved internally.

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

MCP Tools

The Breeks MCP adapter currently exposes 51 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.

Project

5 tools

breeks.project.get_context

Get Project Context

Retrieve project context including members, recent records, tasks, documents, and open items.

read-only

breeks.project.get

Get Project

Retrieve one project by project scope.

read-only

breeks.project.get_recent_activity

Get Recent Project Activity

Retrieve recent audit/activity entries for the project.

read-only

breeks.project.list_tags

List Tags

List the tag catalog.

read-only

breeks.project.add_member

Add Project Member

Add a user as a project member, optionally with assignment scope context.

write

Members

3 tools

breeks.member.resolve_identity

Resolve Member Identity

Resolve or create a channel identity for a project user.

write

breeks.member.search

Search Members

Search project members by text, role, status, scope, or Breeks perceival.

read-only

breeks.member.get

Get Member

Retrieve one project member by member ID or user ID, including scope and Breeks perceival.

read-only

Documents

21 tools

breeks.document.list_versions

List Drawing Versions

List one drawing chain, newest first. Requires document_id; drawing documents only.

read-only

breeks.document.compare_versions

Compare Drawing Versions

Read comparison metadata and page availability for document_id and other_document_id in the same drawing chain. Visual comparison is page-number aligned.

read-only

breeks.document.mark_current

Mark Drawing Current

Explicitly promote a processed pending drawing revision. Requires document_id and expected_current_document_id from the reviewed history. A stale current ID returns conflict; refresh and obtain a new confirmation.

write

breeks.document.preview_carry_forward

Preview Drawing Carry Forward

Preview tags, annotations, record links, task links and blocked page mappings from document_id to target_document_id in the same drawing chain.

read-only

breeks.document.carry_forward

Carry Drawing Relationships Forward

Copy only explicitly selected project_tag_ids, annotation_ids, record_link_ids and task_ids from document_id to target_document_id. Preserves historical relationships; blocked selections fail atomically.

writeidempotent

breeks.document.search

Search Documents

Search project documents with text and metadata filters.

read-only

breeks.document.get

Get Document

Retrieve document metadata, comments, tags, and activity.

read-only

breeks.document.get_pages

Get Document Pages

Retrieve page metadata for a document.

read-only

breeks.document.get_processing_status

Get Document Processing Status

Retrieve processing status and extraction summary for a document.

read-only

breeks.document.get_activity

Get Document Activity

Retrieve audit activity for a document.

read-only

breeks.document.get_annotations

Get Document Annotations

List annotations for a document or page.

read-only

breeks.document.get_annotation_request

Get Annotation Request

Check question progress and saved annotation IDs for an annotation request.

read-only

breeks.document.revoke_annotation_request

Revoke Annotation Request

Revoke an active annotation request; requires confirm=true.

writedestructive

breeks.document.update

Update Document

Update editable document metadata.

write

breeks.document.add_comment

Add Document Comment

Add a comment to a document.

write

breeks.document.reprocess

Reprocess Document

Enqueue document reprocessing.

write

breeks.document.tag

Tag Document

Apply a tag to a document.

writeidempotent

breeks.document.untag

Untag Document

Remove a tag from a document.

writedestructive

breeks.document.create_annotation

Create Document Annotation

Create a normalized page annotation on a document.

write

breeks.document.update_annotation

Update Document Annotation

Update a document annotation.

write

breeks.document.delete_annotation

Delete Document Annotation

Delete a document annotation; requires confirm=true.

writedestructive

Record Types

2 tools

breeks.record_type.list

List Record Types

List active project record type definitions.

read-only

breeks.record_type.get_blueprint

Get Record Type Blueprint

Retrieve a record type definition and fields.

read-only

Records

9 tools

breeks.record.create

Create Record

Create a project record draft, including RFI records.

write

breeks.record.search

Search Records

Search records by text, type, status, priority, trade, or tag.

read-only

breeks.record.get

Get Record

Retrieve one record with comments, linked documents, tasks, and activity.

read-only

breeks.record.get_activity

Get Record Activity

Retrieve audit activity for a record.

read-only

breeks.record.update

Update Record

Update a record; closing records still requires record.close permission.

write

breeks.record.add_comment

Add Record Comment

Add a comment to a record.

write

breeks.record.tag

Tag Record

Apply a tag to a record.

writeidempotent

breeks.record.untag

Untag Record

Remove a tag from a record.

writedestructive

breeks.record.link_document

Link Record Document

Link a document, page, or annotation to a record.

write

Tasks

8 tools

breeks.task.create

Create Task

Create a project Kanban task or nested subtask.

write

breeks.task.search

Search Tasks

Search tasks by text, hierarchy, and metadata filters.

read-only

breeks.task.get

Get Task

Retrieve one task with comments and direct children.

read-only

breeks.task.update

Update Task

Update editable task fields.

write

breeks.task.assign

Assign Task

Assign a task to a project member.

write

breeks.task.move_status

Move Task Status

Move a task between Kanban statuses.

write

breeks.task.link_document

Link Task Document

Link a document, page, or annotation to a task.

write

breeks.task.add_comment

Add Task Comment

Add a comment to a task.

write

Notifications

1 tool

breeks.notification.send

Send Notification

Queue a project notification.

write

Schedules

2 tools

breeks.schedule.create_reminder

Create Reminder

Create a scheduled reminder.

write

breeks.schedule.cancel_reminder

Cancel Reminder

Cancel a scheduled reminder.

writedestructive

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 in Documents. Existing tokens are not converted, and the old public request, image, and answer routes return 410 Gone. The separate /ask utility and Share comment workflow remain available.

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 uses MCP_ACCESS_TOKEN. The MCP service uses AGENT_TOOL_SERVICE_TOKEN to call the API.

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