Last Verified: September 2026 — commands checked against docker/mcp-gateway (v0.43.3) and the official Docker MCP Toolkit docs
Every MCP server you add to Claude Code is another claude mcp add line, another Node or Python process running on your machine with your user’s full permissions, and often another API key sitting in a config file. By the fifth server, it’s hard to say what’s installed, what it can touch, or where the keys are.
Docker MCP Gateway collapses all of that into a single entry. Claude Code connects to one server, MCP_DOCKER, and the gateway runs every MCP server you pick from Docker’s catalog, each in its own container. Containers are capped at 1 CPU and 2 GB of memory and get no host filesystem access unless you grant it. Credentials live in Docker Desktop instead of your config files. It’s open source (MIT) and ships built into Docker Desktop as the MCP Toolkit.
This guide uses GitHub and Playwright as the example servers. If you set up Playwright the direct way with our Playwright MCP guide, this is the containerized alternative.
Quick Start
In Docker Desktop, go to Settings → Beta features → Enable Docker MCP Toolkit → Apply. Then, in a terminal:
docker mcp profile create --name dev-toolsdocker mcp profile server add dev-tools \
--server catalog://mcp/docker-mcp-catalog/github-official \
--server catalog://mcp/docker-mcp-catalog/playwrightdocker mcp client connect claude-code --profile dev-tools --globalRestart Claude Code and run claude mcp list. You should see MCP_DOCKER connected. Total time: about 5 minutes.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip the manual steps below and hand the whole job to the agent instead:
You have shell access, Docker, and the `claude mcp` CLI on this machine. Set up the Docker MCP Gateway for Claude Code and report back. Do not tell me it's done unless step 6 actually confirms it:
1. Run `docker mcp --help`. If the command is missing or says Docker Desktop isn't running, stop and tell me to start Docker Desktop and turn on Settings > Beta features > Enable Docker MCP Toolkit.
2. Run `claude mcp list`. If MCP_DOCKER already exists, stop and tell me which profile it uses instead of adding a second one. Also list any existing github or playwright entries, since those would duplicate the gateway's tools.
3. Run `docker mcp profile list`. If there's no dev-tools profile, create it: `docker mcp profile create --name dev-tools`
4. Add two servers to it:
`docker mcp profile server add dev-tools --server catalog://mcp/docker-mcp-catalog/github-official --server catalog://mcp/docker-mcp-catalog/playwright`
5. Connect Claude Code to the profile for all projects: `docker mcp client connect claude-code --profile dev-tools --global`
6. Run `claude mcp list` and confirm MCP_DOCKER shows Connected, then run `docker mcp tools count` and tell me the number.
The GitHub server needs OAuth. Tell me to authorize it in Docker Desktop (MCP Toolkit > the server's Configuration tab > OAuth) instead of asking for a token. Never ask me to paste a token into this chat. If any step fails, give me the exact error and the command that produced it. Do not skip ahead.The agent can’t flip the Beta toggle in Docker Desktop or finish GitHub’s OAuth for you, so the prompt stops and hands those parts back. That’s intentional.
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| Docker Desktop, recent version | Includes the docker mcp CLI plugin and the MCP Toolkit UI. The docs are written for 4.62+ | ~5 min |
| MCP Toolkit enabled | It’s a Beta feature, so it’s off until you turn it on in Settings | 1 min |
| Claude Code installed | The client that connects to the gateway | 0 min |
| A GitHub account (for this example) | The GitHub server authorizes through OAuth in Docker Desktop | 1 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Turn on the MCP Toolkit
~1 min
Open Docker Desktop settings, select Beta features, check Enable Docker MCP Toolkit, and select Apply. Confirm the CLI is available:
docker mcp --helpStep 2 — Create a profile
~1 min
A profile is a named set of servers. Clients connect to a profile, not to individual servers:
docker mcp profile create --name dev-toolsUpgrading from an older Toolkit? Your existing servers are already in a profile named default.
Step 3 — Add servers from the catalog
~2 min
Browse the catalog to find server IDs:
docker mcp catalog server ls mcp/docker-mcp-catalogThen add the ones you want. Server URIs follow catalog://mcp/docker-mcp-catalog/<server-id>:
docker mcp profile server add dev-tools \
--server catalog://mcp/docker-mcp-catalog/github-official \
--server catalog://mcp/docker-mcp-catalog/playwrightFor servers that need OAuth, such as GitHub, open Docker Desktop → MCP Toolkit, select the server, choose OAuth in its Configuration tab, and follow the link. No token needs to be pasted anywhere.
Step 4 — Connect Claude Code
~1 min
--global writes the system-wide Claude Code config. Leave it off and the gateway is set up only for the current git repo:
docker mcp client connect claude-code --profile dev-tools --globalPrefer to register it yourself? This does the same thing with Claude Code’s own command:
claude mcp add MCP_DOCKER --scope user -- docker mcp gateway run --profile dev-toolsStep 5 — Trim the tool list (optional)
~2 min
Every tool from every server in the profile lands in Claude’s context. Check the count and disable the ones you don’t use:
docker mcp tools countdocker mcp profile tools dev-tools --disable <server>.<tool>What Each Piece Does
| Piece | What It Does |
|---|---|
MCP Gateway (docker mcp gateway run) | The single MCP server Claude Code talks to. It starts server containers on demand and routes tool calls to them |
Catalog (mcp/docker-mcp-catalog) | Docker’s curated list of containerized MCP servers, like GitHub, Playwright, and Notion |
| Profile | A named group of servers plus their config and tool allowlist. One profile per project works well |
| Client connection | Writes the MCP_DOCKER entry into Claude Code’s config so it launches the gateway with your profile |
| Secrets & OAuth | Credentials are stored in the Docker Desktop VM (since 4.43.0), not in your MCP config files |
| Container limits | 1 CPU and 2 GB of memory per tool container, no host filesystem unless you grant mounts, and tool requests carrying secrets are blocked |
Verify It’s Actually Working
claude mcp list! github also listed separately → remove the old direct entry to avoid duplicate tools
✘ MCP_DOCKER Failed to connect → start Docker Desktop and check the MCP Toolkit is enabled
Then run the test prompt from Docker’s own docs:
Use the GitHub MCP server to show me my open pull requestsIf Claude calls a GitHub tool through MCP_DOCKER and lists real pull requests, the gateway, the container, and the OAuth credential are all working.
Common Mistakes to Avoid
- Skipping the Beta toggle. The MCP Toolkit is off by default. Without it,
docker mcpcommands fail or behave unexpectedly. - Keeping the old direct entries. If
githuborplaywrightis still registered withclaude mcp add, Claude sees every tool twice. Remove the direct entries once the gateway works. - Forgetting
--global. Without it, the connection only applies to the git repo you ran it in, and other projects won’t seeMCP_DOCKER. - “Docker Desktop is not running” on WSL2 or Docker CE. Set
export DOCKER_MCP_IN_CONTAINER=1, and outside Docker Desktop, rundocker mcp feature enable profilesonce. - Loading every server into one profile. Each server adds tools to Claude’s context. Use separate profiles per project and disable tools you never call.
Q&A
Is it free?
Yes. The gateway is open source under the MIT license and ships with Docker Desktop. The separate “Docker AI Governance” enterprise edition is invite-only, but you don’t need it for this setup.
Why run MCP servers in containers at all?
A server started with npx or uvx runs with your user’s full access. In a container it’s limited to 1 CPU and 2 GB, can’t see your files unless you mount them, and gets credentials from Docker instead of an environment variable.
Can Claude add servers on its own?
With Dynamic MCP, an experimental feature, the agent gets tools like mcp-find and mcp-add to search the catalog and add servers mid-session. If you want a fixed set, run docker mcp feature disable dynamic-tools.
Does it work without Docker Desktop?
The CLI plugin can run independently, for example on Docker CE or in WSL2. Set DOCKER_MCP_IN_CONTAINER=1 and enable profiles with docker mcp feature enable profiles.
How do I remove it?
docker mcp client disconnect claude-code --global (or claude mcp remove MCP_DOCKER), then turn off the Toolkit in Beta features. Stored credentials can be listed and removed with docker mcp secret ls and docker mcp secret rm.
Official Resources
- Get started with Docker MCP Toolkit — official setup walkthrough
- Use MCP Toolkit from the CLI — every
docker mcpcommand used here - docker/mcp-gateway on GitHub — source code and releases
- Docker MCP Catalog — browse available servers
If this guide cut your Claude Code MCP config down to one line, follow us on X for more setup guides and prompt tips.
Leave a Reply