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
Reverse proxy	get_proxy_status, list_proxy_routes, list_proxy_certs, list_proxy_bans, get_proxy_metrics, create_proxy_route, update_proxy_route, delete_proxy_route, ban_ip, unban_ip

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.

Connect your AI client (stdio)

The assistant spawns the server locally and it dials out to your instance — so a local setup can manage production: point SOL2DOCKER_SERVER_URL at your prod URL. However you add it, the moving parts are identical — run npx -y @sol2docker/mcp with two env vars:

• SOL2DOCKER_SERVER_URL — your instance, e.g. https://sol2docker.example.com
• SOL2DOCKER_API_TOKEN — the s2d_… token you created above

Pick your client (swap in your URL + token):

Claude Code (CLI)

claude mcp add sol2docker \
  --scope local \
  --env SOL2DOCKER_SERVER_URL=https://sol2docker.example.com \
  --env SOL2DOCKER_API_TOKEN=s2d_… \
  -- npx -y @sol2docker/mcp

--scope local is just for the current project; use --scope user to make it available in every project, or --scope project to share it with your team via a checked-in .mcp.json.

Codex CLI

codex mcp add sol2docker \
  --env SOL2DOCKER_SERVER_URL=https://sol2docker.example.com \
  --env SOL2DOCKER_API_TOKEN=s2d_… \
  -- npx -y @sol2docker/mcp

…or add it to ~/.codex/config.toml directly:

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

Gemini CLI

gemini mcp add sol2docker \
  -e SOL2DOCKER_SERVER_URL=https://sol2docker.example.com \
  -e SOL2DOCKER_API_TOKEN=s2d_… \
  npx -y @sol2docker/mcp

VS Code (Copilot agent mode)

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

Claude Desktop, Cursor, Windsurf, or any other MCP client (config file)

These are configured by editing an MCP config file — Claude Desktop: claude_desktop_config.json; Cursor: ~/.cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json — with the same server block:

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

Restart/reload the client, then ask it to list_environments to confirm the connection.

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.