ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use Docker Desktop MCP Server

Connect AI clients to Docker Desktop’s MCP Toolkit with profiles, the Gateway, catalog servers, CLI commands, authentication, and troubleshooting.

By the ScreenshotNeo team1 October 20268 min read

Short answer: Docker Desktop’s current product name is the Docker MCP Toolkit. In Docker Desktop 4.62 and later, enable the beta Toolkit, add MCP servers to a profile, then connect your AI client through Docker’s Gateway. Listed clients can be connected from Docker Desktop; an unlisted client can launch the Gateway over stdio with the Docker CLI.

The Toolkit manages containerized MCP servers in profiles and connects them to AI agents. The Gateway receives tool requests from a client, selects the server from the active profile, and starts the server container when needed. See the official Docker MCP Toolkit documentation for release-specific changes.

What you need

  • Docker Desktop 4.62 or later. Docker documents the described interface and CLI commands for this release line, and labels the Toolkit beta.
  • An AI application that supports MCP, such as a client listed in Docker Desktop’s Clients view, or a custom MCP client that can launch a process over stdio.
  • At least one MCP server from the Docker MCP Catalog, with any configuration or credentials that server requires.

Update Docker Desktop before troubleshooting a missing menu or command. Earlier releases have a different interface.

Method 1: Set up the Toolkit in Docker Desktop

1. Enable Docker MCP Toolkit

  1. Open Docker Desktop.
  2. Open Settings and choose Beta features.
  3. Enable Docker MCP Toolkit, then select Apply.

2. Create or select a profile

Open MCP Toolkit > Profiles. Create a profile for the project, or use the existing default profile. A profile is the named collection of servers that the Gateway exposes to a connected client.

Use separate profiles when projects need different credentials or server sets. This keeps a client from seeing every server you have configured.

3. Add servers from the Catalog

  1. Open Catalog.
  2. Select an MCP server.
  3. Add it to the intended profile.
  4. If the server shows Configuration Required, complete those fields before connecting a client.

The catalog includes local containerized servers and remote services. Local servers run in Docker containers and can work offline after download. Remote services run on the provider’s infrastructure and may require OAuth or another provider-specific authentication method.

4. Connect an AI client

  1. Open Clients in the Toolkit.
  2. Find your AI application.
  3. Select Connect.
  4. Follow the client-specific instructions shown by Docker Desktop.

Docker’s supported-client list can change. If your application is not listed, use the manual stdio method below.

5. Verify both sides of the connection

A connected client only proves that the client can reach the Gateway. Confirm that the intended server and tool are also available.

  • In Claude Code, for example, run claude mcp list if that is the verification command for your installed client.
  • In an AI chat, ask the client to list available MCP tools, then invoke a harmless read-only tool.
  • Check the active Docker profile if a server you expect is missing.

Method 2: Configure Docker MCP Toolkit from the CLI

The CLI is useful for repeatable project setup, scripts, and clients that Docker Desktop does not list. Run these commands in a terminal with Docker Desktop 4.62 or later.

Create a profile

docker mcp profile create --name my-project

Add a catalog server

Replace the catalog reference and server ID with the values shown for the server you selected.

docker mcp profile server add my-project --server catalog://<catalog-ref>/<server-id>

List servers in the profile

docker mcp profile server ls my-project

Run the Gateway

docker mcp gateway run --profile my-project

If you omit --profile, Docker uses the default profile.

Connect a supported client

docker mcp client connect <client> --profile my-project

Use --global when you intentionally want system-wide client configuration instead of the current repository or project scope. Client names and flags depend on the installed Docker Desktop release; check the current command reference before scripting this step.

Connect an unlisted MCP client over stdio

A generic JSON-based MCP client needs to launch Docker as the command and pass the Gateway arguments. The exact configuration keys vary by client, but the process definition is:

{
  "command": "docker",
  "args": ["mcp", "gateway", "run", "--profile", "my-project"]
}

For a client using Claude Desktop’s configuration shape, the same process is commonly nested under an mcpServers object:

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

Use the configuration format documented by your client. Do not paste the generic example unchanged if that client expects a different file location or schema.

Understand the Docker MCP architecture

Part Role
MCP client The AI application that requests tools or resources.
MCP server Software that provides tools or resources. Catalog servers may run locally in containers or remotely on a provider’s infrastructure.
Profile A named collection of configured servers made available through the Gateway.
Gateway The central proxy that routes a client request to the selected server and starts a local server container when needed.

This separation explains common failures. A client can be connected to the Gateway while the wrong profile is active, a server is not installed, or a server still needs credentials.

Authentication and permissions

OAuth servers

For servers that use OAuth, add the server, open its configuration, select OAuth, complete authorization in the browser, and return to Docker Desktop. Authorized services are visible under the OAuth tab, where access can be revoked.

Token or credential configuration

Authentication is server-specific. Some servers require a username and personal access token rather than OAuth. Follow the selected server’s Catalog page and configuration fields; do not assume that every server supports the same login flow.

Review access before connecting

  • Grant only the services and scopes the server needs.
  • Review requested mounts and credentials.
  • Remember that an explicit host mount can expose files to a tool.
  • Review external service access even when the server itself runs locally.

Docker documents Toolkit controls of 1 CPU and 2 GB memory for MCP tools, no host filesystem access by default, and explicit mounts. Docker also documents blocking requests to and from tools that contain sensitive information such as secrets. These controls reduce exposure but do not replace reviewing a server’s permissions and configuration.

Local catalog servers versus remote services

Consideration Local containerized server Remote service
Where it runs In a Docker container managed by the Toolkit. On the provider’s infrastructure.
Offline use Docker says local servers can work offline after download. Requires the provider and network connection.
Authentication May still need credentials for an external API. Often uses OAuth or provider-specific credentials.
Operational dependency Depends on Docker Desktop, local resources, and downloaded images. Depends on the provider’s availability and network path.

Common errors and fixes

Error or symptom Likely cause Fix
MCP Toolkit is missing Docker Desktop is older than 4.62, or the beta feature is disabled. Update Docker Desktop, open Settings > Beta features, enable Docker MCP Toolkit, and apply the change.
docker mcp is unknown The installed Desktop release does not include the documented CLI. Update Docker Desktop and verify the Docker CLI is using that installation.
Client connects but no tools appear The client is using the wrong profile, or the profile has no servers. Run docker mcp profile server ls <profile>, then reconnect with the intended profile.
Server shows Configuration Required Required credentials or settings are incomplete. Open the server configuration in the Catalog and complete every required field.
OAuth authorization fails The browser flow was canceled, the provider denied access, or the client session expired. Retry OAuth from the server configuration, check the provider’s requested scopes, and revoke stale authorization before starting again.
Local server will not start Image download, Docker Desktop state, resource limits, or server configuration problem. Confirm Docker Desktop is running, check the server configuration, and retry after the image is available.
Remote server times out Network or provider dependency. Check connectivity and provider status, then retry. A local catalog server may be preferable for offline work.
Tools cannot read host files Host filesystem access is disabled by default. Add only the explicit mount the server requires and review the path before reconnecting.
Custom client exits immediately Incorrect JSON shape, command path, or stdio argument list. Test docker mcp gateway run --profile <profile> directly, then copy the exact command and arguments into the client’s documented MCP format.

Performance, reliability, and operating cost

Performance

  • Local servers avoid a provider network round trip after their images are downloaded, but they consume the documented Toolkit allocation of 1 CPU and 2 GB memory for MCP tools.
  • Remote tools depend on network latency and the provider’s service.
  • Keep profiles focused so the client has fewer tools to discover and fewer credentials to manage.
  • Use a stable named profile in scripts instead of relying on whichever profile happens to be default.

Reliability

  • Pin your Docker Desktop version in team setup notes because the Toolkit is beta and menus, supported clients, and flags can change.
  • Document each server’s authentication method and required configuration.
  • For critical workflows, test the Gateway, the selected profile, and the specific tool in a clean session.
  • Keep a fallback path for remote services when your workflow must operate offline.

Cost

The reviewed Docker documentation does not provide a topic-specific price for the Toolkit or catalog servers. Your practical costs can include Docker Desktop licensing where applicable, local compute and storage, and fees charged by a remote provider or external API. Check each provider’s terms instead of assuming catalog entries share one pricing model.

Or skip the browser setup

If your goal is simply to produce website screenshots for an AI workflow, ScreenshotNeo provides a direct screenshot API and an MCP server. You can keep the Docker MCP setup for other tools and call ScreenshotNeo when you need a clean capture.

See the ScreenshotNeo API documentation for the current options. This one-call example captures Stripe as a WebP file:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.

FAQ

Is Docker Desktop MCP the same as an MCP server?

No. Docker Desktop provides the Toolkit and Gateway that manage and route requests to individual MCP servers.

Do I need a separate profile for every project?

No, but separate profiles are useful when projects need different server sets, credentials, or permissions.

Can a remote MCP server run without Docker?

Remote catalog services run on the provider’s infrastructure. The client still reaches them through the Toolkit and Gateway configuration.

What should I do when Docker Desktop lists no client?

Use a client configuration that launches docker mcp gateway run --profile <profile-id> over stdio, adapting the JSON keys to that client’s schema.

Does enabling the Toolkit give every server host access?

No. Docker documents no host filesystem access by default. Explicit mounts, credentials, external API permissions, and server behavior still require review.

Where do I check whether a command or client name changed?

Use the current Docker MCP Toolkit, CLI, Gateway, client, and Catalog documentation for the Docker Desktop version installed on your machine.

Keep reading