Dynamic MCP

Dynamic MCP enables AI agents to discover and add MCP servers on-demand during a conversation, without manual configuration. Instead of pre-configuring every MCP server before starting your agent session, clients can search the MCP Catalog and add servers as needed.

This capability is enabled automatically when you connect an MCP client to the MCP Toolkit. The gateway provides a set of primordial tools that agents use to discover and manage servers during runtime.

Dynamic MCP is an experimental feature in early development. While you're welcome to try it out and explore its capabilities, you may encounter unexpected behavior or limitations. Feedback is welcome via at GitHub issues for bug reports and GitHub discussions for general questions and feature requests.

How it works

When you connect a client to the MCP Gateway, the gateway exposes a small set of management tools alongside any MCP servers in your active profile. These management tools let agents interact with the gateway's configuration:

Tool	Description
`mcp-find`	Search for MCP servers in the catalog by name or description
`mcp-add`	Add a new MCP server to the current session
`mcp-config-set`	Configure settings for an MCP server
`mcp-remove`	Remove an MCP server from the session
`mcp-exec`	Execute a tool by name that exists in the current session
`code-mode`	Create a JavaScript-enabled tool that combines multiple MCP server tools

With these tools available, an agent can search the catalog, add servers, handle authentication, and use newly added tools directly without requiring a restart or manual configuration.

Dynamically added servers and tools are associated with your current session only. They're not persisted to your profile. When you start a new session, only servers you've added to your profile through the MCP Toolkit or Profiles are available.

Prerequisites

To use Dynamic MCP, you need:

Docker Desktop version 4.50 or later, with MCP Toolkit enabled
An LLM application that supports MCP (such as Claude Desktop, Visual Studio Code, or Claude Code)
Your client configured to connect to the MCP Gateway

See Get started with Docker MCP Toolkit for setup instructions.

Usage

Dynamic MCP is enabled automatically when you use the MCP Toolkit. Your connected clients can now use mcp-find, mcp-add, and other management tools during conversations.

To see Dynamic MCP in action, connect your AI client to the Docker MCP Toolkit and try this prompt:

plaintext

What MCP servers can I use for working with SQL databases?

Given this prompt, your agent will use the mcp-find tool provided by MCP Toolkit to search for SQL-related servers in the MCP Catalog.

And to add a server to a session, simply write a prompt and the MCP Toolkit takes care of installing and running the server:

plaintext

Add the postgres mcp server

Tool composition with code mode

The code-mode tool is available as an experimental capability for creating custom JavaScript functions that combine multiple MCP server tools. The intended use case is to enable workflows that coordinate multiple services in a single operation.

Note

Code mode is in early development and is not yet reliable for general use. The documentation intentionally omits usage examples at this time.

The core Dynamic MCP capabilities (mcp-find, mcp-add, mcp-config-set, mcp-remove) work as documented and are the recommended focus for current use.

The architecture works as follows:

The agent calls code-mode with a list of server names and a tool name
The gateway creates a sandbox with access to those servers' tools
A new tool is registered in the current session with the specified name
The agent calls the newly created tool
The code executes in the sandbox with access to the specified tools
Results are returned to the agent

The sandbox can only interact with the outside world through MCP tools, which are already running in isolated containers with restricted privileges.

Security considerations

Dynamic MCP maintains the same security model as static MCP server configuration in MCP Toolkit:

All servers in the MCP Catalog are built, signed, and maintained by Docker
Servers run in isolated containers with restricted resources
Code mode runs agent-written JavaScript in an isolated sandbox that can only interact through MCP tools
Credentials are managed by the gateway and injected securely into containers

The key difference with dynamic capabilities is that agents can add new tools during runtime.

Disabling Dynamic MCP

Dynamic MCP is enabled by default in the MCP Toolkit. If you prefer to use only statically configured MCP servers, you can disable the dynamic tools feature:

console

$ docker mcp feature disable dynamic-tools

To re-enable the feature later: