Skip to main content

MCP connections

Caplo can expose a hosted MCP server so external AI clients such as Cursor and Claude Code can use repository lookup and repository write tools against your workspace data.

Supported flow​

The hosted MCP server uses:

  • the public MCP URL https://app.caplo.ai/mcp
  • browser-based Supabase OAuth
  • a required workspace choice during consent
  • refresh tokens managed by the MCP client

Connect a client​

  1. Add https://app.caplo.ai/mcp in your MCP client.
  2. Start the connection flow from the client.
  3. Sign in to Caplo in the browser if needed.
  4. Review the client name and requested scopes.
  5. Choose the workspace this connection should use.
  6. Approve the connection.

After approval, the MCP client reconnects to Caplo and can call the hosted tools.

Workspace binding​

Each MCP connection is bound to exactly one workspace.

  • The workspace is chosen during browser consent.
  • The connection stays bound to that workspace until you revoke access.
  • MCP requests do not let the client choose a different workspace per tool call.

This keeps repository access predictable and aligned with Caplo's workspace-scoped security model.

Switch to another workspace​

To use another workspace for the same MCP client:

  1. Open Settings > MCP connections in Caplo.
  2. Revoke the existing authorization.
  3. Reconnect from Cursor or Claude Code.
  4. Choose the new workspace during consent.

Caplo does not support an inline “switch workspace” action for an existing MCP authorization.

Available tools​

The hosted MCP server exposes a small repository-focused surface:

  • Search entities
  • Load direct relations for repository entities
  • Load a graph neighborhood around selected entities
  • List valid relation types for an entity-type pair
  • Load and persist Process-owned BPMN diagrams
  • Load, persist, and delete an entity document (get_document, persist_document, delete_document)
  • Create, update, and delete repository entities
  • Create, update, and delete repository relations
  • Delete a Process-owned BPMN diagram without deleting the Process
  • Inspect entity-type and relation-type property definitions before writing
  • List, create, get, and update drafts
  • List, read, publish, and delete pages

Lookup tools can read a draft when you pass draftId. Writes go into a draft — create one first, or reuse an open draft from list_drafts / get_draft. Publish and delete of drafts stay in the Caplo UI.

The property-definition tools let an MCP client discover the effective writable fields for the current workspace, including built-in properties and workspace-specific custom properties. When list_entity_type_properties omits entityType, it returns the entity types currently enabled for that workspace. Tool inputs only offer those enabled entity types, and only the enabled relation types. A type turned off in the metamodel is not listed, so the client will not try to create it.

Each property includes valueSchema, example, and writeHelp for the JSON value to send on create_entities / update_entity. Use that contract for structured fields such as Phase in / Phase out (dateOrRange: { "earliest": "YYYY-MM-DD", "latest": "YYYY-MM-DD" }). Equal bounds are an exact day. A year, quarter, or month is the first and last day of that bucket. Omit Phase in when the item is already active; omit Phase out when there is no planned retirement.

The stable public MCP tool names are:

  • search_entities
  • list_entity_relations
  • list_valid_relation_types
  • search_graph_neighborhood
  • get_bpmn_diagram
  • persist_bpmn_diagram
  • delete_bpmn_diagram
  • get_document
  • persist_document
  • delete_document
  • create_entities
  • update_entity
  • delete_entity
  • create_relations
  • update_relation
  • delete_relation
  • list_drafts
  • create_draft
  • get_draft
  • update_draft
  • list_entity_type_properties
  • list_relation_type_properties
  • list_reports
  • get_report
  • create_report
  • update_report
  • delete_report
  • get_report_definition_schema
  • list_pages
  • get_page
  • create_page_upload
  • publish_page
  • delete_page
  • export_page_preview

Each tool returns structured JSON. MCP clients that support machine-readable tool results can read that JSON directly instead of parsing plain text.

get_bpmn_diagram returns a compact outline: named process elements, entity bindings, and the XML size in codeBytes. Sequence flows, message flows, and conditions stay in the XML. Pass includeCode: true when you need that XML, for example before updating the diagram. persist_bpmn_diagram confirms the write with url, the process identity, bindings, and codeBytes, and does not return the XML you just sent. get_document returns a summary (url, documentId, contentBytes, textPreview). Pass includeContent: true to also get Markdown. persist_document accepts Markdown and returns url, documentId, and contentBytes. delete_document removes the document and leaves the entity. What to write on the page, and how it appears in Caplo, is covered in Entity documents.

Both tools include a url field that opens the Process entity BPMN tab in Caplo. After creating or updating a diagram, the tool text also starts with Open the BPMN diagram: {url} so the client can share that link.

Draft tools include a url field that opens the draft review page. After creating or updating a draft, the tool text also starts with Open the draft: {url}.

create_entities and create_relations each take up to 100 items in one call. Create the entities first, then the relations. Relation endpoints are { type, name }, including names from that entity call. Omit name on a relation unless it needs a specific label. The stored name is then the relation type label, with a numeric suffix when that pair already has a live one. A removed relation with the same key is restored and comes back existing.

Each item comes back as created, existing, or error. The text is a count line plus one short line per item. Relation lines are the stored direction, such as created Recruiting (capability) child of HR (capability) <id> reversed. reversed means that item's endpoints were swapped to match the stored direction. The JSON repeats those compact fields and does not echo properties.

update_entity, delete_entity, update_relation, and delete_relation return a one-line summary in the tool text and the full object in the structured result.

Saved reports work the same way as other draft writes. create_report, update_report, and delete_report need a draftId from create_draft or list_drafts. They change that draft only. Publishing the draft stays in Caplo. list_reports and get_report can omit draftId to read the published workspace. get_report_definition_schema returns the definition shape and one example when you need coloring, filters, charts, or roadmap timing. update_report keeps omitted top-level fields. Coloring, timing, pace, and property display merge by layer id. capability-fitness stays valid only on a capability layer, so changing that layer's type without replacing the coloring is rejected. A bar chart uses later layers only when groupBy.mode is relation-path. After creating, reading, or updating a report, the tool text starts with Open the report: {url}. That link opens the report in Caplo, including the draft when the call used one.

publish_page and delete_page require an open draftId. They do not change the live page. Publish the draft in Caplo. Omit isPrivate and the new page follows the draft: personal in a personal draft, shared in a shared draft. A personal page cannot be saved in a shared draft. Styles, scripts, images, and fonts stay in the file, and the page cannot load another host. Repository rows stay in Caplo. When the page opens it reads them through caplo, for the live workspace, the open draft, or the snapshot the viewer has open. Leave those rows out of the HTML. Write the HTML to a local file. create_page_upload returns a one-hour upload link and a token. POST the file to that link, then pass the token to publish_page. That call does not take the HTML. get_page returns a one-hour download link and the file size, not the HTML. Save that file, edit it, and upload it again. Page tools include a url that opens /pages/{id}, with ?draft={draftId} when the call is draft-scoped. export_page_preview returns a short-lived JavaScript download that installs window.caplo with the rows you can see, so a local HTML file can be opened in a browser before publish_page. The tool result is the link and counts, not the rows. Leave that script out of the uploaded file. Pages explains how to open, organize, and review a page, and lists the caplo call shape, the row fields, and which way each relation points.

Manage existing connections​

Open Settings > MCP connections to review:

  • which MCP clients currently have access
  • which workspace each connection is bound to
  • the scopes granted to each client
  • the revoke action for each authorization

Troubleshooting​

The client asks me to authenticate again​

That usually means the client needs a fresh access token or refresh failed. Reconnect through the normal browser flow.

I need a different workspace​

Revoke the authorization in Caplo settings, then reconnect and choose the correct workspace.

The connection works in Caplo but not in the MCP client​

Check that:

  • you used the /mcp URL
  • the browser consent completed successfully
  • the selected workspace contains the repository data you expect
  • the MCP client finished reconnecting after authorization