MCP Server¶

Doco-CD exposes a stateless Model Context Protocol server at POST /mcp using Streamable HTTP transport. The endpoint uses the main HTTP_PORT and follows the main server's TLS configuration.

Enable the Server¶

Enable the server with MCP_ENABLED: true and provide an API secret using API_SECRET or API_SECRET_FILE (see REST API Authentication):

services:
  app:
    environment:
      MCP_ENABLED: "true"
      API_SECRET: your-api-key

MCP_ENABLED defaults to false. Enabling it without an API secret causes application configuration validation to fail.

Authentication¶

Every request must include the same x-api-key header used by the REST API:

x-api-key: your-api-key

Client Configuration Examples¶

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "doco-cd": {
      "type": "remote",
      "url": "https://cd.example.com/mcp",
      "headers": {
        "x-api-key": "{env:DOCO_CD_API_SECRET}"
      }
    }
  }
}

{
  "servers": {
    "doco-cd": {
      "type": "http",
      "url": "https://cd.example.com/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "docoCdApiKey",
      "description": "Doco-CD API key",
      "password": true
    }
  ],
  "servers": {
    "doco-cd": {
      "type": "http",
      "url": "https://cd.example.com/mcp",
      "headers": {
        "x-api-key": "${input:docoCdApiKey}"
      }
    }
  }
}

Available Tools¶

Swarm tools are always advertised. Calls fail if Docker Swarm features are unavailable or disabled.

Long-Running Tools¶

trigger_scheduled_job and trigger_poll accept a wait argument that defaults to true.

• wait: true: the tool blocks until the operation completes and returns the final status. Application shutdown cancels active runs after a 10-second grace period. Client disconnects do not cancel the running operation.
• wait: false: the tool returns an accepted status and job_id immediately. The job continues under the application lifecycle; neither client disconnects nor request cancellation can stop it, but application shutdown does.

To poll progress with wait: false:

1. Call the tool with wait: false to receive a job_id.
2. Call get_deployment_run with that job_id until status is terminal.

Poll Input¶

trigger_poll requires a configs array with at most 32 items and accepts wait as an optional top-level field:

{
  "configs": [
    {
      "source": "git",
      "url": "https://github.com/example/application.git",
      "reference": "main"
    }
  ],
  "wait": false
}

Each item in configs accepts these fields:

The interval and run_once fields are not accepted; MCP-triggered polls always run once immediately. All configs in one request run with bounded concurrency controlled by MAX_CONCURRENT_DEPLOYMENTS (default: 4).

Operational Notes¶

• The server is stateless. Clients must not depend on server-side MCP sessions between requests.
• Request bodies are limited by MAX_PAYLOAD_SIZE.
• Deployment run history is stored in memory and is lost when doco-cd restarts.
• Tool errors can include structured output such as a job_id; clients should inspect both the MCP error flag and the structured result fields.
• MCP tool request, error, and duration metrics are exposed by the Prometheus endpoint: doco_cd_mcp_requests_total, doco_cd_mcp_errors_total, and doco_cd_mcp_request_duration_seconds.