mcp: gateway dynamic mcp tools

dvdksn · dvdksn · commit dc482fbfc71c · 2025-10-31T15:39:59.000+01:00
Signed-off-by: David Karlsson &lt;35727626+dvdksn@users.noreply.github.com&gt;
diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/_index.md b/content/manuals/ai/mcp-catalog-and-toolkit/_index.md
@@ -23,14 +23,18 @@ grid:
    description: Learn about the MCP Toolkit to manage MCP servers and clients
    icon: /icons/toolkit.svg
    link: /ai/mcp-catalog-and-toolkit/toolkit/
+ - title: Dynamic MCP
+   description: Discover and add MCP servers on-demand using natural language
+   icon: search
+   link: /ai/mcp-catalog-and-toolkit/dynamic-mcp/
  - title: MCP Gateway
    description: Learn about the underlying technology that powers the MCP Toolkit
    icon: developer_board
-   link: /ai/mcp-catalog-and-toolkit/toolkit/
+   link: /ai/mcp-catalog-and-toolkit/mcp-gateway/
  - title: Docker Hub MCP server
    description: Explore about the Docker Hub server for searching images, managing repositories, and more
    icon: device_hub
-   link: /ai/mcp-catalog-and-toolkit/toolkit/
+   link: /ai/mcp-catalog-and-toolkit/hub-mcp/
 ---
 
 {{< summary-bar feature_name="Docker MCP Catalog and Toolkit" >}}
diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md b/content/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md
@@ -0,0 +1,146 @@
+---
+title: Dynamic MCP
+linkTitle: Dynamic MCP
+description: Discover and add MCP servers on-demand using natural language with Dynamic MCP servers
+keywords: dynamic mcps, mcp discovery, mcp-find, mcp-add, code-mode, ai agents, model context protocol
+weight: 35
+params:
+  sidebar:
+    badge:
+      color: green
+      text: New
+---
+
+Dynamic MCP enables AI agents to discover, add, and compose 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](/manuals/ai/mcp-catalog-and-toolkit/catalog.md),
+add servers as needed, and even create new tools that combine multiple MCP
+servers together.
+
+This capability is enabled automatically when you connect an MCP client to the
+[MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md). The gateway
+provides a set of primordial tools that agents use to discover and manage
+servers during runtime.
+
+{{% experimental %}}
+
+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.
+
+{{% /experimental %}}
+
+## 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 you've already enabled. 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                                    |
+| `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_. When you start a new session, previously added servers are not
+automatically included.
+
+## Prerequisites
+
+To use Dynamic MCP, you need:
+
+- Docker Desktop version 4.50 or later, with [MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md) 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](/manuals/ai/mcp-catalog-and-toolkit/get-started.md)
+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](./catalog.md).
+
+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
+
+Beyond discovering and adding servers individually, agents can use
+`code-mode` to create new tools that combine multiple MCP servers. This
+enables sophisticated workflows that coordinate multiple services in a single
+operation.
+
+When you invoke `code-mode`, you specify which servers should be available
+in a sandboxed JavaScript environment. The agent can then write code that calls
+multiple tools, processes their results, and returns unified output.
+
+### How code mode works
+
+1. The agent calls `code-mode` with a list of server names
+2. The gateway creates a sandbox with access to those servers' tools
+3. The agent writes JavaScript code that uses the available tools
+4. The code runs in the sandbox, isolated from your host system
+5. Results are returned to the agent
+
+The agent's code 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:
+
+```console
+$ docker mcp feature enable dynamic-tools
+```
+
+After changing this setting, you may need to restart any connected MCP clients.
+
+## Further reading
+
+Check out the [Dynamic MCP servers with Docker](https://docker.com/blog) blog
+post for more examples and inspiration on how you can use dynamic tools.
diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md b/content/manuals/ai/mcp-catalog-and-toolkit/toolkit.md
@@ -24,6 +24,12 @@ It is the fastest way from MCP tool discovery to local execution.
 - Zero manual setup: No dependency management, runtime configuration, or setup required.
 - Functions as both an MCP server aggregator and a gateway for clients to access installed MCP servers.
 
+> [!TIP]
+> The MCP Toolkit includes [Dynamic MCP](/manuals/ai/mcp-catalog-and-toolkit/dynamic-mcp.md),
+> which enables AI agents to discover, add, and compose MCP servers on-demand during
+> conversations, without manual configuration. Your agent can search the catalog and
+> add tools as needed when you connect to the gateway.
+
 ## How the MCP Toolkit works
 
 MCP introduces two core concepts: MCP clients and MCP servers.
