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
  • Create and update repository entities
  • Create and update repository relations
  • Inspect entity-type and relation-type property definitions before writing

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.

The stable public MCP tool names are:

  • search_entities
  • list_entity_relations
  • search_graph_neighborhood
  • create_entity
  • update_entity
  • create_relation
  • update_relation
  • list_entity_type_properties
  • list_relation_type_properties

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

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