Docker MCP Toolkit: Gateway, Catalog and Claude Setup, Step by Step

Most MCP setups start the same way. You paste a JSON block into Claude Desktop, paste a slightly different one into Claude Code, launch a third server through npx, and leave a personal access token sitting in plain text inside a config file. It works until it doesn't, and then you are hunting through three files to find out why a tool vanished. The Docker MCP Toolkit swaps that pile for one managed layer: servers that run as containers, a catalog that supplies them, and a single gateway that Claude talks to. This article sets up all three, connects Claude Desktop and Claude Code, and shows how to prove that every tool is alive before you rely on it.

What the Toolkit Actually Does

The Toolkit lives inside Docker Desktop. It runs MCP servers as isolated containers, groups them into named profiles, and exposes each profile to AI clients through the MCP Gateway. Claude never launches a server on its own. It talks to one endpoint, and the gateway routes each request to the right container.

The practical win is separation. Your editor, your chat app and your terminal agent all point at the same gateway, while the servers, their credentials and their resource limits stay in Docker's hands instead of being copied into every client config.

The Gateway in Plain Terms

Think of the gateway as a front desk. Every request from Claude arrives there. The gateway picks the server that should answer, starts its container when needed, and hands the result back. The chain is short: Claude, then the gateway, then the containerized server.

The gateway is open source under the MIT license and installs as a Docker CLI plugin, so docker mcp --help works as soon as the Toolkit is on. It speaks stdio by default, which suits one client. When several clients need the same gateway, run it over HTTP streaming:

docker mcp gateway run --port 8080 --transport streaming

Copy Prompt

The container layer is what makes this tidy. Before the Toolkit, each server needed its own runtime on your machine: Node for one, Python for the next, a pinned version for a third. A containerized server carries its runtime with it, so the only thing your laptop needs is Docker. Updating or removing a server stops being a cleanup chore, because the server was never installed on the host in the first place.

Catalog, Profiles and Clients

Three terms carry the whole system, and every command in this article touches one of them.

💡 Tip: one profile can serve several clients. Configure it once and every connected app sees the same tools.

Before You Install Anything

You need very little, but each item matters.

Docker Desktop and the Beta Toggle

The Toolkit requires Docker Desktop 4.62 or later, and it sits behind a beta switch:

1. Open Docker Desktop and go to Settings.
2. Select Beta features.
3. Turn on Docker MCP Toolkit.
4. Select Apply.

An MCP Toolkit entry now appears in the Docker Desktop menu. If you used an earlier version of the Toolkit, your existing configuration migrates into a profile named default, so nothing needs rebuilding.

Which Claude Clients Work

Two Claude clients matter here. Claude Desktop connects from the Clients tab with a single button. Claude Code connects from the terminal with one command. Docker's docs also list Cursor, Zed and Visual Studio Code, which helps when your team is split across editors, since all of them can read the same profile.

💡 Tip: install Claude Code before you begin if you plan to use the terminal route. The connection check later in this walkthrough relies on its claude mcp list command.

Build Your First Profile

A profile is a workspace. A research profile might hold a search server and a notes server, while a release profile holds GitHub and a monitoring server. Keeping them apart means Claude only sees the tools that matter for the job at hand.

Three profile layouts show the idea:

• Research: a notes server for background material and one search-style server for lookups.
• Release: GitHub for pull requests and a monitoring server such as Grafana for the dashboards you check before shipping.
• Support: read-only access to a payments server such as Stripe, with the write tools switched off.

Create It in Docker Desktop

1. Open MCP Toolkit and select the Profiles tab.
2. Select Create profile.
3. Type a name, such as Frontend development.
4. Add servers and clients now, or skip both and do it later.
5. Select Create.

Create It From the Terminal

The same result takes two commands:

docker mcp profile create --name dev-tools --server catalog://<server-reference>
docker mcp profile list

Copy Prompt

Replace the placeholder with the reference of a server from your catalog. Three more subcommands handle upkeep:

• docker mcp profile server add and remove change the server list.
• docker mcp profile config <id> --set (or --get, --del) edits a profile's settings.
• docker mcp profile tools <id> --enable (or --disable) controls which tools Claude can call.

Choose Servers From the Catalog

The Docker MCP Catalog holds hundreds of servers. Docker's own pages put the count at more than 200 in one place and more than 300 in another, which suggests it keeps growing. Browse it from the Catalog tab, select Add to, and pick your profile. Servers marked Configuration Required need a credential or a setting before they work.

Verified, Docker-Built and Remote

The catalog mixes three kinds of server:

• Verified partner servers from companies such as New Relic, Stripe and Grafana, published with provenance and SBOM metadata.
• Docker-built servers, built and signed by Docker, that run locally and live in the mcp namespace on Docker Hub.
• Remote servers hosted in the cloud, such as GitHub and Notion.

💡 Tip: teams that need tighter control can build a custom catalog and import it with docker mcp catalog pull <oci-reference>, so people only see approved servers.

Servers Worth Adding First

Start small. Every server you add puts more tool descriptions in front of Claude, and a tight profile keeps its choices sharper. Four easy starting points:

Secrets and OAuth

Remote servers such as GitHub use OAuth. Docker opens a browser window, you approve access, and the credential stays managed by Docker instead of being pasted into JSON. For servers that need static secrets, run docker mcp secret --help to see the options, and docker mcp oauth --help for the authorization commands. Docker's docs add that requests carrying sensitive information are blocked.

💡 Tip: never paste a real token into a chat window or a shared config. If a server asks for one, store it through the Toolkit.

Connect Claude Desktop and Claude Code

Claude Desktop in Two Clicks

1. In Docker Desktop, open MCP Toolkit and select the Clients tab.
2. Find Claude Desktop and select Connect.
3. Restart Claude Desktop.

After the restart, open the Search and tools menu. An entry named MCP_DOCKER should be listed and switched on. Every server in your profile now sits behind that one entry.

Claude Code From the Terminal

Claude Code connects through a single command:

docker mcp client connect claude-code --global
claude mcp list

Copy Prompt

The second command should print a line like MCP_DOCKER: docker mcp gateway run - ✓ Connected. To tie a client to one profile instead of everything, the connect command accepts --profile, as in docker mcp client connect vscode --profile my_profile. The general form is docker mcp client connect [client-name] --profile [id].

The --global flag applies the connection system-wide instead of to the current project, which suits a personal machine. Leave it off when a single repository should have its own tool set.

Manual JSON Fallback

Some clients read their own JSON file and have no connect button. Add the gateway as a stdio server:

{
  "servers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "my_profile"],
      "type": "stdio"
    }
  }
}

Copy Prompt

Match the top-level property name your client documents, because some clients expect mcpServers where this snippet says servers. One entry replaces the stack of separate server blocks you had before.

Because the gateway keeps your tools in one place, none of this has to be rebuilt when you change clients. Swap Claude Desktop for Claude Code and the same profile follows you.

Test, Debug and Lock It Down

Verify the Connection

Run a prompt that forces a real tool call. Docker's own example works well: "Use the GitHub MCP server to show me my open pull requests." If Claude answers with data from your account, the full chain is working. For a lower-level view, docker mcp tools ls lists every tool the gateway currently exposes, and docker mcp client ls shows which clients are connected.

Test in three passes. First, ask Claude to list the tools it can see, which confirms the profile loaded. Second, call a read-only tool, such as listing pull requests, which confirms the credentials work. Third, and only then, try an action that changes something, and do it in a throwaway repository or a test workspace so a typo costs nothing.

Fix the Slow First Start

The gateway needs roughly 15 to 25 seconds to come up. Most "it's broken" moments are really "it's still waking up". Wait half a minute before you change anything, then check this table.

Limits, Allowlists and Dynamic Tools

Docker applies guardrails by default. Each server container is capped at 1 CPU and 2 GB of memory, filesystem access stays off until you grant it, and images in the mcp namespace are digitally signed. Inside a profile, a tool allowlist narrows what Claude may call at all.

One feature deserves a deliberate decision. Dynamic MCP lets Claude search the catalog and add a server in the middle of a conversation, using management tools the gateway exposes: mcp-find, mcp-add, mcp-config-set, mcp-remove, mcp-exec, and an experimental code-mode. It switches on automatically with the Toolkit. If you want a fixed tool set, turn it off:

docker mcp feature disable dynamic-tools

Copy Prompt

Turn it back on later with docker mcp feature enable dynamic-tools.

How to Use Sonnet 5 on PicassoIA

Setup work produces a lot of text to read: error output, profile commands, notes for teammates. Claude Sonnet 5 sits in the Large Language Models collection on PicassoIA and handles exactly that. It reads a plain request or a stack trace, accepts a screenshot, and returns commands or fixes you can check against Docker's docs.

Here is the routine, from page to answer:

1. Open the Claude Sonnet 5 page.
2. Paste your problem into Prompt: the exact error text, or the output of claude mcp list.
3. Pick an effort level. low is the default and skips extended thinking, so answers come back fast. Raise it to high or max for a tangled problem that spans several files.
4. Attach a screenshot of the Docker Desktop screen in Image if the problem is visual.
5. Add a System Prompt once, such as "You are a DevOps assistant. Reply with exact docker mcp commands and one sentence of context."
6. Leave Max Tokens at 8192 for long answers, and run it.

💡 Tip: Sonnet 5 cannot see your machine. Treat its commands as drafts and check each one against Docker's documentation before you run it.

Other models on the platform fit different habits. Claude Fable 5 targets harder coding tasks, GPT 5.6 Sol takes on complex code, Gemini 3.1 Pro handles long multimodal questions, and Kimi K2.6 is built for agent work.

Try It With Your Own Images

Once Claude reaches your servers through one gateway, the next step is giving those workflows something to look at. A GitHub server can draft release notes, a Notion server can hold the brief, and an image model can produce the header photo in the same sitting.

Every photo in this article came from P Image, generated from long, specific prompts that name the lens, the light and the surface textures. For other looks, try Flux 2 Pro, GPT Image 2, Seedream 4.5 or Nano Banana Pro. When a still should move, Seedance 2.0, Veo 3.1 and Kling v3 Video turn a prompt or a single image into short clips.

Open Picasso IA, pick a model, and describe one scene the way you would brief a photographer: the subject, the angle, the light, the lens. Generate a few variations, keep the one that matches your article, and drop it in. The first image takes a minute, and the second takes less.