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. compact_mirrors accepts a wait argument that defaults to false.

• 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 or request cancellation 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.

Mirror compaction is also cancelled during a self-update handover. A repack stops and keeps the old packfiles; a copy finishes the current mirror before stopping.

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, schedule and run_once fields are not accepted; MCP-triggered polls always run once immediately. MCP-triggered polls count as manual deployments for sync windows. All configs in one request run with bounded concurrency controlled by MAX_CONCURRENT_DEPLOYMENTS (default: 4).

Logging¶

MCP SDK, authentication, and tool logs include the JSON field component: "mcp". Operation logs also include this field when they use the MCP handler's logger.

Routine MCP SDK messages, including session connections and disconnections, use the debug level. Set LOG_LEVEL to debug to see them. These messages are hidden at info and higher log levels. Warnings, errors, and application operation logs keep their original levels.

To filter MCP logs in Loki, parse the JSON field: {service_name="doco-cd"} | json | component="mcp". Replace the service_name value with your deployment's label value. The component field does not need to be an indexed Loki label.

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 bounded and stored in memory; after a restart, only recoverable retained scheduled one_off executions can be reconstructed, not completed API history.
• 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.