Collabnix / Cheatsheets
All cheatsheets
AIIntermediate

Docker MCP Gateway Cheatsheet

Run a single MCP endpoint that fronts many containerized MCP servers for any client.

What it is

Use the MCP Gateway when you want one stable endpoint for AI clients (Claude Desktop, Cursor, VS Code Copilot) that multiplexes multiple MCP servers managed via the Docker MCP Toolkit.

Installation

Bundled with the Docker MCP Toolkit. Enable with `docker mcp feature enable docker-mcp-toolkit`.

Quick start

docker mcp gateway run

Start the gateway on the default transport.

docker mcp gateway run --profile dev

Front only the servers in a specific profile.

docker mcp tools --profile dev

List tools that the gateway will expose.

Common commands

TaskCommandDescription
Run gateway
docker mcp gateway run
Start the gateway in the foreground.
Run with profile
docker mcp gateway run --profile <name>
Limit exposed servers to a profile.
List profiles
docker mcp profile list
Profiles available to the gateway.
Inspect tools
docker mcp tools --profile <name>
All tools the gateway will advertise.
Add server
docker mcp profile server add <profile> <server>
Adds a catalog server the gateway will expose.

Useful flags

FlagExampleMeaning
--profile
docker mcp gateway run --profile dev
Profile to load servers/secrets from.
--transport
docker mcp gateway run --transport stdio
Transport mode (stdio or sse, depending on client).
--port
docker mcp gateway run --transport sse --port 8811
Listen port for SSE transport.

Real-world examples

Wire Claude Desktop to the gateway (stdio)

{
  "mcpServers": {
    "docker": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "dev"]
    }
  }
}

Add to Claude Desktop's claude_desktop_config.json.

Run gateway over SSE for browser clients

docker mcp gateway run --transport sse --port 8811 --profile dev

Best practices

  • One gateway per profile keeps tool surfaces lean and auditable.
  • Prefer stdio for desktop AI clients; SSE for browser or remote clients.
  • Restart the gateway after adding/removing servers so clients see the new toolset.

Troubleshooting

Client connects but sees no tools

Verify the profile actually has servers added.

docker mcp profile server list <profile>

Port already in use (SSE)

Pick a different port.

docker mcp gateway run --transport sse --port 8812

Secrets missing inside a tool call

Set them and restart the gateway.

docker mcp secret set <KEY> <VALUE>

Official Docker Docs references

Last reviewed: