Docker MCP Toolkit: connect AI agents to development tools through reviewed profiles

An AI client can answer development questions without accessing your issue tracker. Once you connect a tool server, the same client may read private repositories, change tickets or invoke infrastructure APIs. The connection is an authority decision as well as an installation step.

With Docker MCP Toolkit, client requests pass through the Docker MCP gateway, which only exposes the servers in an explicit profile. The guide also shows how to verify both allowed and forbidden behaviour before trusting the setup.

Docker MCP Toolkit organizes those integrations into profiles and routes client requests through a gateway. This guide builds a small, reviewable setup for a development task and explains the checks that a successful connection does not cover.

The profile-based instructions follow Docker's documentation for Desktop 4.62 and later, reviewed on 11 October 2026. Toolkit is labelled beta. Earlier releases have different commands or interfaces; confirm the installed version rather than mixing old server-management snippets with the current workflow.

Our MCP security guide explains the underlying server-trust and approval model.

Step 1: Define one integration and one task

Begin with a harmless read of a synthetic resource. Avoid starting with a production database or an account that administers every repository in an organization.

Write down the server maintainer, image or remote endpoint, intended tools, credential scope and resource boundary. Review the actual tool schemas and descriptions. A server that offers both reading and writing needs more scrutiny than its marketing summary suggests.

A catalog entry's provenance is useful evidence, but it does not prove every operation is appropriate for your project.

Step 2: Create a dedicated profile

Enable Toolkit through the supported Desktop settings, or follow Docker's separate gateway installation instructions if using Docker Engine without Desktop. Confirm the appropriate plugin is present before scripting profile commands.

The following example creates only a named development profile. Run it in your own experimental environment; choose a name that does not collide with an existing profile.

docker mcp --help
docker mcp profile create --name incident-lab
docker mcp profile list
docker mcp profile show incident-lab

Inspect available server IDs through the catalog or Desktop interface. Add only the reviewed server and complete its required configuration. Do not import a large team profile simply to fix a missing connection.

Use separate profiles for substantially different trust scopes. Development resource access and production administration should not become indistinguishable just because both use the same client application.

Step 3: Configure the least privileged credential

Prefer a dedicated account and narrow provider permissions. For a repository read task, a token capable of deploying production or creating organization administrators is unnecessary.

Set up authentication through the supported credential or OAuth workflow. Keep secret values out of profile JSON, screenshots, terminal history and exported troubleshooting notes. Inspect a shared profile before importing it even when credentials are excluded from the normal sharing format.

The gateway can manage authentication, but the downstream service remains responsible for enforcing its account permissions. Test that enforcement with an unrelated synthetic resource that should be denied.

Step 4: Connect the client to the explicit profile

For a client supporting stdio MCP, the gateway command can be configured as follows. Client configuration schemas vary; adapt the outer structure to that application's own documented format.

{
  "mcpServers": {
    "development-tools": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "incident-lab"]
    }
  }
}

Avoid omitting the profile and unintentionally using an existing default collection. Inspect the tools exposed after connection rather than relying solely on a connected status indicator.

If the client times out during gateway startup, inspect logs and the documented startup behavior. Increasing a client timeout can address initialization timing; it cannot repair wrong credentials, a missing server configuration or a denied destination.

Step 5: Review dynamic discovery

Docker documents Dynamic MCP as experimental and enabled by default in Toolkit. It allows an agent to discover and add servers during a session. That behavior deserves an explicit decision when the task contract calls for a fixed tool set.

Inspect the feature and available catalog before starting. Where the policy requires static integrations, Docker documents disabling dynamic tools with this command:

docker mcp feature disable dynamic-tools

This is a setting change, not a named-profile-only example. Evaluate its effect on other clients and reconnect them as documented. Avoid presenting a static profile as a complete restriction while leaving session discovery unexamined.

Step 6: Verify both allowed and forbidden behavior

Request one bounded read from your synthetic resource. Confirm the result came from the intended account and server, and that no unrelated resource was accessed.

Use the gateway's available logs and client diagnostics to identify the failing layer. A malformed tool argument, an authentication failure and a container startup error require different corrections.

Step 7: Retire capabilities at the right owner

Disconnect the client when the task ends and remove unnecessary profile integrations deliberately. Docker's FAQ notes that stored credentials can remain after server removal. Revoke provider access separately where required, then verify denial.

Keep a small inventory of approved server versions and scopes. Review changes after upgrading the gateway or replacing a server image; a newly added tool can change the effective authority of an established connection.

Our secure NestJS MCP server guide covers implementing the server-side boundary. For a controlled integration with your application's real permissions and audit trail, discuss the project with Cloudsoft Zone.

Featured image: Cloudsoft Zone technical layout with docker artwork by dotCloud, Inc. (Apache License 2.0). Product mark resized proportionally for identification; no endorsement implied. Layout: CC BY-SA 4.0.