MCP Mode

Expose your docker-agent agents as MCP tools for use in Claude Desktop, Claude Code, and other MCP-compatible applications.

Why MCP Mode?

The docker agent serve mcp command makes your agents available to any application that supports the Model Context Protocol. This means you can:

ℹ️ What is MCP?

The Model Context Protocol is an open standard for connecting AI tools. See also Remote MCP Servers for connecting to cloud services.

Basic Usage

# Expose a local config (stdio transport, the default)
$ docker agent serve mcp ./agent.yaml

# Expose from a registry
$ docker agent serve mcp agentcatalog/pirate

# Set the working directory
$ docker agent serve mcp ./agent.yaml --working-dir /path/to/project

Transports

By default, serve mcp uses the stdio transport — ideal for clients that spawn the server as a subprocess (Claude Desktop, Claude Code, Cursor, …).

To expose the MCP server over streaming HTTP instead, pass --http:

# Streaming HTTP transport on the default 127.0.0.1:8081
$ docker agent serve mcp ./agent.yaml --http

# Override the listen address / port
$ docker agent serve mcp ./agent.yaml --http --listen 0.0.0.0:9090
Flag Default Description
--http false Use streaming HTTP transport instead of stdio.
-l, --listen 127.0.0.1:8081 Address to listen on when --http is enabled.
-a, --agent all agents Expose a single named agent instead of every agent in the config.

Runtime configuration flags such as --working-dir, --env-from-file, --models-gateway, and hook flags are also available — see the CLI reference.

Using with Claude Desktop

Add a configuration to your Claude Desktop MCP settings file:

{
  "mcpServers": {
    "myagent": {
      "command": "/usr/local/bin/docker",
      "args": [
        "agent", 
        "serve",
        "mcp",
        "agentcatalog/coder",
        "--working-dir",
        "/home/user/projects"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your_key_here",
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Using with Claude Code

$ claude mcp add --transport stdio myagent \
  --env OPENAI_API_KEY=$OPENAI_API_KEY \
  --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -- docker agent serve mcp agentcatalog/pirate --working-dir $(pwd)

Multi-Agent in MCP Mode

When you expose a multi-agent configuration via MCP, each agent becomes a separate tool in the MCP client:

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Main coordinator
    sub_agents: [designer, engineer]
  designer:
    model: openai/gpt-5-mini
    description: UI/UX design specialist
  engineer:
    model: anthropic/claude-sonnet-4-0
    description: Software engineer

All three agents (root, designer, engineer) appear as separate tools in Claude Desktop or Claude Code.

Troubleshooting

← Previous CLI Reference