AI / MCP integration

Sol2Docker ships a Model Context Protocol server so AI assistants can talk to your infrastructure — "what's unhealthy on prod?", "deploy this stack", "scale the api service to 5" — and act on it. It's a separate image, ghcr.io/sol2docker/mcp.

The MCP server is a thin, outbound-only client: each tool is an authenticated call to the Sol2Docker API, and the server's RBAC decides what your token may actually do. It holds no state and makes no Docker calls of its own.

What the agent can do

The tools are curated and environment-scoped (the agent calls list_environments first, then get_resources):

Area	Tools
Discover	list_environments, environment_overview, get_resources, get_environment_health, get_docker_info
Inspect	inspect_container, container_stats, inspect_image, swarm_cluster, get_stack_compose
Observe	tail_container_logs, tail_events (bounded snapshots), list_jobs, get_job
Act	container_action, run_container, remove_container, pull_image, deploy_stack, stack_action, deploy_compose, deployment_action, scale_service, service_action, create_environment, delete_environment

Long operations (deploys, pulls, lifecycle) run to completion and return the final job status + log.

Setup

1. Create an API token in the dashboard under Account → API tokens (see the API guide). For an agent, least privilege matters — prefer a read-only token, or a dedicated user with a narrow role, so the agent can't do more than you intend.
2. Connect the MCP server one of two ways.

Desktop assistants (stdio)

Claude Desktop, Cursor, and similar spawn the server locally. Add to the client's MCP config:

{
  "mcpServers": {
    "sol2docker": {
      "command": "npx",
      "args": ["-y", "@sol2docker/mcp"],
      "env": {
        "SOL2DOCKER_SERVER_URL": "https://sol2docker.example.com",
        "SOL2DOCKER_API_TOKEN": "s2d_…"
      }
    }
  }
}

Hosted (Streamable HTTP)

Run the image and connect agents to its /mcp endpoint:

docker run -d --name sol2docker-mcp -p 8930:8930 \
  -e SOL2DOCKER_SERVER_URL=https://sol2docker.example.com \
  -e SOL2DOCKER_API_TOKEN=s2d_… \
  ghcr.io/sol2docker/mcp
# MCP endpoint: http://<host>:8930/mcp

Safety

• RBAC is the real boundary — the agent can only do what the token's role allows.
• SOL2DOCKER_MCP_READONLY=true additionally hides every write/deploy tool, so the agent can observe but never change anything — a good default for exploration.
• Transport is fail-closed — plain http to a non-loopback host is refused (the token would be exposed); use https.

Var	Default	Meaning
SOL2DOCKER_SERVER_URL	—	Your Sol2Docker instance (required)
SOL2DOCKER_API_TOKEN	—	Personal API token s2d_… (required)
SOL2DOCKER_MCP_TRANSPORT	stdio	stdio or http
SOL2DOCKER_MCP_READONLY	false	Hide write tools
SOL2DOCKER_MCP_PORT	8930	http bind port

Start read-only, confirm the agent sees what you expect, then widen the token's role only as far as you need.