Skip to main content
Version: 8.9 (unreleased)

Enable and connect

Enable the Orchestration Cluster MCP Server and configure MCP clients to connect.

Enable the Orchestration Cluster MCP Server​

The MCP server is opt-in and must be enabled before MCP clients can connect. Depending on your deployment, enable it as follows:

The MCP server is enabled by default in Camunda 8 Run. No additional configuration is needed.

For a full reference of MCP configuration properties, see Property reference.

Connect an MCP client​

Once the MCP server is enabled, you can connect any MCP-compliant client. The approach depends on your client's capabilities and your authentication requirements.

MCP endpoint URL​

The MCP server is served at /mcp/cluster on the Orchestration Cluster. The full endpoint URL depends on your deployment type:

DeploymentMCP endpoint URL
Camunda 8 Runhttp://localhost:8080/mcp/cluster
Docker Composehttp://localhost:8080/mcp/cluster
SaaShttps://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/mcp/cluster
Self-Managed (custom)https://<your-host>/mcp/cluster

For SaaS, find your Region Id and Cluster Id in the Camunda Console under Cluster Details.

Direct HTTP connection​

If your Orchestration Cluster does not require authentication, for example when running locally with Camunda 8 Run or Docker Compose, you can connect directly to the MCP server endpoint without any additional tooling.

Any MCP client that supports Streamable HTTP can be used. For authenticated environments, use c8ctl mcp-proxy instead.

{
  "servers": {
    "camunda": {
      "type": "http",
      "url": "http://localhost:8080/mcp/cluster"
    }
  }
}

Use c8ctl mcp-proxy​

Many MCP clients, such as VS Code (GitHub Copilot) and Claude Code, do not natively support the OAuth 2.0 client credentials flow required for authenticated environments. The c8ctl mcp-proxy command bridges this gap by providing a local STDIO-to-Remote HTTP proxy that handles authentication transparently.

The proxy authenticates to the MCP server using OAuth 2.0 client credentials, and exposes a local STDIO MCP interface that your client connects to.

Prerequisites​

Configuration​

Add the following to your MCP client configuration (for example, .vscode/mcp.json for VS Code, or claude_desktop_config.json for Claude Code):

{
  "servers": {
    "camunda-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@camunda8/cli", "mcp-proxy"],
      "env": {
        "CAMUNDA_BASE_URL": "https://<cluster-base-url>",
        "CAMUNDA_CLIENT_ID": "<client-id>",
        "CAMUNDA_CLIENT_SECRET": "<client-secret>",
        "CAMUNDA_OAUTH_URL": "https://<token-url>/oauth/token",
        "CAMUNDA_TOKEN_AUDIENCE": "<token-audience>"
      }
    }
  }
}
VariableDescription
CAMUNDA_BASE_URLBase URL of your Orchestration Cluster, without the /mcp/cluster path (see MCP endpoint URL).
CAMUNDA_CLIENT_IDOAuth client ID from your API client credentials.
CAMUNDA_CLIENT_SECRETOAuth client secret from your API client credentials.
CAMUNDA_OAUTH_URLOAuth token endpoint URL.
CAMUNDA_TOKEN_AUDIENCEToken audience for the Orchestration Cluster API.
Where to find these values

When you create API client credentials in the Camunda Console, all required connection details — including the base URL, OAuth endpoint, client ID, and audience — are displayed on the credentials page. Copy them into the configuration above.

For the full list of supported environment variables, see the c8ctl documentation.

Use with the MCP Client connectors​

You can also connect to the MCP server from within a BPMN process using Camunda's MCP Client connectors. This allows an AI agent running in an agentic orchestration workflow to interact with Camunda's own operational data — for example, to query incidents or start processes as part of an automated workflow.

The MCP Remote Client connector connects to remote MCP servers over HTTP. Configure it in the properties panel with the following settings:

  • Transport type: Streamable HTTP.
  • URL: Your MCP endpoint URL (see above).
  • Authentication: OAuth 2.0.
FieldValue
OAuth 2.0 token endpointYour OAuth token endpoint (https://login.cloud.camunda.io/oauth/token for SaaS).
Client IDYour OAuth client ID.
Client secretYour OAuth client secret. Use secrets (for example, {{secrets.MCP_CLIENT_SECRET}}).
AudienceThe audience for your cluster API (zeebe.camunda.io for SaaS).
Client authenticationSend client credentials in body.

For more details, see MCP Remote Client connector.