# DockTail Cloud for AI agents: MCP server and REST API

> DockTail Cloud gives an AI agent the evidence it needs to find the root cause of an outage end to end: failed checks, Docker events, the container logs from the moment it broke, and host vitals. Connect Claude Code, Cursor, Codex, VS Code or Claude Desktop over MCP, or use the REST API from scripts.

Web page: https://docktail.org/cloud/agents/ · About DockTail Cloud: https://docktail.org/cloud.md · Reference: https://docktail.org/docs/cloud/#api-and-mcp-server

## Before you start

- The user needs a DockTail Cloud account (https://cloud.docktail.org/login) and a workspace with a plan or a running trial. An agent cannot sign up or subscribe for them. Homelab and Team start with a 30-day free trial that needs a card.
- The user creates an API key on the **MCP** page (https://cloud.docktail.org/mcp) or the **API** page (https://cloud.docktail.org/api-access): **Create key**, pick a scope, copy the `dtk_...` key (shown once).
- Scopes: `read` (default) reaches every read tool and endpoint and is enough to investigate any incident. `read_write` can also acknowledge and resolve incidents and start or stop maintenance.

## MCP server

- Endpoint: `https://cloud.docktail.org/api/mcp` (Streamable HTTP, stateless)
- Header: `Authorization: Bearer dtk_...`

Claude Code:

```bash
claude mcp add --transport http docktail https://cloud.docktail.org/api/mcp \
  --header "Authorization: Bearer dtk_..."
```

Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "docktail": {
      "url": "https://cloud.docktail.org/api/mcp",
      "headers": { "Authorization": "Bearer dtk_..." }
    }
  }
}
```

Codex (`~/.codex/config.toml`), with `DOCKTAIL_API_KEY` set in the shell Codex starts from:

```toml
[mcp_servers.docktail]
url = "https://cloud.docktail.org/api/mcp"
bearer_token_env_var = "DOCKTAIL_API_KEY"
```

VS Code uses `.vscode/mcp.json` with `"type": "http"` and asks for the key on first start. Claude Desktop connects through the `mcp-remote` bridge (needs Node.js). The MCP page in Cloud shows the exact snippet for each client.

### Tools

Read (any key):

- `get_workspace`: workspace, plan and fleet summary. Start here.
- `list_hosts`, `get_host`: hosts, vitals, services, containers, recent incidents and Docker events.
- `list_services`, `get_service`: health per vantage, transitions and events.
- `list_incidents`, `get_incident`: incidents, with the vantages and host vitals at open and the Docker events.
- `get_incident_logs`: the container log tail captured at the failure.
- `list_events`: activity by host or service.
- `list_maintenance_windows`: active and scheduled maintenance.

Write (`read_write` keys only; use only when the user asks):

- `acknowledge_incident`, `resolve_incident`, `start_maintenance`, `stop_maintenance`.

## Finding a root cause

1. `list_incidents` to find the incident (filter by status, host, service or date).
2. `get_incident` for the failed vantages, Docker events (exit code, OOM kill, restart loop) and host vitals at open.
3. `get_incident_logs` for the log tail from the moment it failed.
4. `get_host`, `get_service` or `list_events` for context: what else changed, whether the tailnet still advertised the service.
5. Report the cause, the evidence and the fix. Only read unless the user asks for a change.

## REST API

- Base URL: `https://cloud.docktail.org/api/v1`, same bearer key
- OpenAPI 3.1: `https://cloud.docktail.org/api/v1/openapi.json` (public)
- Reads: `GET /workspace`, `/hosts`, `/hosts/{id}`, `/services`, `/services/{id}`, `/incidents`, `/incidents/{id}`, `/incidents/{id}/logs`, `/events`, `/maintenance`
- Writes (`read_write`): `POST /incidents/{id}/ack`, `/incidents/{id}/resolve`, `/maintenance/start`, `/maintenance/stop`

```bash
curl -H "Authorization: Bearer $DOCKTAIL_API_KEY" \
  "https://cloud.docktail.org/api/v1/incidents?status=open"
```

Responses are camelCase JSON; errors are `{"error": "<sentence>"}`. API and MCP share a limit of 120 requests per key per minute.

## Boundaries

An API key sees what the dashboard shows and nothing else. Neither the API nor the DockTail agent on the hosts can run commands or deploy. Writes are limited to incident and maintenance state in Cloud and are logged under the key's name. Revoking a key on the MCP or API page leaves the other keys working.