Merge pull request #23631 from dvdksn/mcp-client-verify

mcp: add instructions for verifying client connections

content/manuals/ai/mcp-catalog-and-toolkit/get-started.md

@@ -4,6 +4,8 @@ linkTitle: Get started
 description: Learn how to quickly install and use the MCP Toolkit to set up servers and clients.
 keywords: Docker MCP Toolkit, MCP server, MCP client, AI agents
 weight: 10
+params:
+  test_prompt: Use the GitHub MCP server to show me my open pull requests
 ---
 
 {{< summary-bar feature_name="Docker MCP Toolkit" >}}
@@ -23,24 +25,21 @@ Before you begin, make sure you meet the following requirements to get started w
 3. Select **Enable Docker MCP Toolkit**.
 4. Select **Apply**.
 
-There are multiple ways to get started with Docker MCP Toolkit. You can:
+The **Learning center** in Docker Desktop provides walkthroughs and resources
+to help you get started with Docker products and features. On the **MCP
+Toolkit** page, the **Get started** walkthrough that guides you through
+installing an MCP server, connecting a client, and testing your setup.
 
-- The **Learning center** in Docker Desktop provides walkthroughs and resources
-  to help you get started with Docker products and features.
+Alternatively, follow the step-by-step instructions on this page to:
 
-  On the **MCP Toolkit** page, the **Get started** walkthrough that guides you
-  through installing an MCP server, connecting a client, and testing your
-  setup.
+- [Install MCP servers](#install-mcp-servers)
+- [Connect clients](#connect-clients)
+- [Verify connections](#verify-connections)
 
-- Alternatively, follow the step-by-step instructions on this page to use
-  Docker Desktop or the CLI to [Install an MCP server](#install-an-mcp-server),
-  [add a client, and test your setup](#install-an-mcp-client-and-test-your-setup)
-  with example prompts.
+## Install MCP servers
 
-## Install an MCP server
-
-{{< tabs group="release" >}}
-{{< tab name="From Docker Desktop">}}
+{{< tabs >}}
+{{< tab name="Docker Desktop">}}
 
 1. In Docker Desktop, select **MCP Toolkit** and select the **Catalog** tab.
 2. Search for the **GitHub Official** server from the catalog and then select the plus icon to add it.
@@ -56,7 +55,7 @@ There are multiple ways to get started with Docker MCP Toolkit. You can:
 5. Search for the **Playwright** server from the catalog and add it.
 
 {{< /tab >}}
-{{< tab name="From the Docker CLI">}}
+{{< tab name="CLI">}}
 
 1. Add the GitHub Official MCP server. Run:
 
@@ -85,54 +84,325 @@ There are multiple ways to get started with Docker MCP Toolkit. You can:
    {{< /tab >}}
    {{< /tabs >}}
 
-You’ve now successfully added an MCP server. Next, install an MCP client and test your setup with an example prompt.
+You’ve now successfully added an MCP server. Next, connect an MCP client to use
+the MCP Toolkit in an AI application.
 
-## Install an MCP client and test your setup
+## Connect clients
 
-After you've installed MCP servers, you can add clients to the MCP Toolkit. These clients can interact with the installed MCP servers, turning the MCP Toolkit into a gateway. In the following section, let’s add the Claude Desktop client.
-
-{{< tabs group="release" >}}
-{{< tab name="From Docker Desktop">}}
+To connect a client to MCP Toolkit:
 
 1. In Docker Desktop, select **MCP Toolkit** and select the **Clients** tab.
-2. Find **Claude Desktop** and select **Connect**.
+2. Find your application in the list.
+3. Select **Connect** to configure the client.
 
-   If Claude Desktop isn't installed, select **Download** to install it, then select **Connect**.
+If your client isn't listed, you can connect the MCP Toolkit manually over
+`stdio` by configuring your client to run the following command:
 
-3. Restart Claude Desktop if it's running, and it can now access all the servers in the MCP Toolkit.
-4. Open Claude Desktop and run a test by submitting the following prompt:
+```plaintext
+docker mcp gateway run
+```
 
-   ```text
-   Take a screenshot of the header element on docs.docker.com
-   ```
+For example, if your client uses a JSON file to configure MCP servers, you may
+add an entry like:
 
-   Claude prompts you for permissions and shares a screenshot of the header element from the Docker documentation page.
+```json {title="Example configuration"
+{
+  "servers": {
+    "MCP_DOCKER": {
+      "command": "docker",
+      "args": ["mcp", "gateway", "run"],
+      "type": "stdio"
+    }
+  }
+}
+```
 
-   ![Screenshot showing the header of Docker docs.](./images/claude-desktop-example.png)
+Consult the documentation of the application you're using for instructions on
+how to set up MCP servers manually.
+
+## Verify connections
+
+Refer to the relevant section for instructions on how to verify that your setup
+is working:
+
+- [Claude Code](#claude-code)
+- [Claude Desktop](#claude-desktop)
+- [OpenAI Codex](#codex)
+- [Continue](#continue)
+- [Cursor](#cursor)
+- [Gemini](#gemini)
+- [Goose](#goose)
+- [Gordon](#gordon)
+- [LM Studio](#lm-studio)
+- [OpenCode](#opencode)
+- [Sema4.ai](#sema4)
+- [Visual Studio Code](#vscode)
+- [Zed](#zed)
+
+### Claude Code
+
+If you configured the MCP Toolkit for a specific project, navigate to the
+relevant project directory. Then run `claude mcp list`. The output should show
+`MCP_DOCKER` with a "connected" status:
+
+```console
+$ claude mcp list
+Checking MCP server health...
+
+MCP_DOCKER: docker mcp gateway run - ✓ Connected
+```
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```console
+$ claude "{{% param test_prompt %}}"
+```
+
+### Claude Desktop
+
+Restart Claude Desktop and check the **Search and tools** menu in the chat
+input. You should see the `MCP_DOCKER` server listed and enabled:
+
+![Claude Desktop](images/claude-desktop.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param test_prompt %}}
+```
+
+### Codex
+
+Run `codex mcp list` to view active MCP servers and their statuses. The
+`MCP_DOCKER` server should appear in the list with an "enabled" status:
+
+```console
+$ codex mcp list
+Name        Command  Args             Env  Cwd  Status   Auth
+MCP_DOCKER  docker   mcp gateway run  -    -    enabled  Unsupported
+```
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```console
+$ codex "{{% param test_prompt %}}"
+```
+
+### Continue
+
+Launch the Continue terminal UI by running `cn`. Use the `/mcp` command to view
+active MCP servers and their statuses. The `MCP_DOCKER` server should appear in
+the list with a "connected" status:
+
+```plaintext
+   MCP Servers
+
+   ➤ 🟢 MCP_DOCKER (🔧75 📝3)
+     🔄 Restart all servers
+     ⏹️ Stop all servers
+     🔍 Explore MCP Servers
+     Back
+
+   ↑/↓ to navigate, Enter to select, Esc to go back
+```
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```console
+$ cn "{{% param test_prompt %}}"
+```
+
+### Cursor
+
+Open Cursor. If you configured the MCP Toolkit for a specific project, open the
+relevant project directory. Then navigate to **Cursor Settings > Tools & MCP**.
+You should see `MCP_DOCKER` under **Installed MCP Servers**:
+
+![Cursor](images/cursor.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param test_prompt %}}
+```
+
+### Gemini
+
+Run `gemini mcp list` to view active MCP servers and their statuses. The
+`MCP_DOCKER` should appear in the list with a "connected" status.
+
+```console
+$ gemini mcp list
+Configured MCP servers:
+
+✓ MCP_DOCKER: docker mcp gateway run (stdio) - Connected
+```
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```console
+$ gemini "{{% param test_prompt %}}"
+```
+
+### Goose
+
+{{< tabs >}}
+{{< tab name="Desktop app" >}}
+
+Open the Goose desktop application and select **Extensions** in the sidebar.
+Under **Enabled Extensions**, you should see an extension named `Mcpdocker`:
+
+![Goose desktop app](images/goose.avif)
 
 {{< /tab >}}
-{{< tab name="From the Docker CLI">}}
+{{< tab name="CLI" >}}
 
-1. In a terminal window, run the following commands to connect the Claude Desktop client:
+Run `goose info -v` and look for an entry named `mcpdocker` under extensions.
+The status should show `enabled: true`:
 
-   ```console
-   $ docker mcp client connect claude-desktop --global
-   ```
-
-2. Restart Claude Desktop if it's running, and it can now access all the servers in the MCP Toolkit.
-3. Open Claude Desktop and run a test by submitting the following prompt using the Sonnet 4 model:
-
-   ```text
-   Take a screenshot of the header element on docs.docker.com
-   ```
-
-   Claude prompts you for permissions and shares a screenshot of the header element from the Docker documentation page.
-
-   ![Screenshot showing the header of Docker docs.](./images/claude-desktop-example.png)
+```console
+$ goose info -v
+…
+    mcpdocker:
+      args:
+      - mcp
+      - gateway
+      - run
+      available_tools: []
+      bundled: null
+      cmd: docker
+      description: The Docker MCP Toolkit allows for easy configuration and consumption of MCP servers from the Docker MCP Catalog
+      enabled: true
+      env_keys: []
+      envs: {}
+      name: mcpdocker
+      timeout: 300
+      type: stdio
+```
 
 {{< /tab >}}
 {{< /tabs >}}
 
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param "test_prompt" %}}
+```
+
+### Gordon
+
+Open the **Ask Gordon** view in Docker Desktop and select the toolbox icon in
+the chat input area. The **MCP Toolkit** tab shows whether MCP Toolkit is
+enabled and displays all the provided tools:
+
+![MCP Toolkit in the Ask Gordon UI](images/ask-gordon.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers, either directly in Docker Desktop or using the CLI:
+
+```console
+$ docker ai "{{% param "test_prompt" %}}"
+```
+
+### LM Studio
+
+Restart LM Studio and start a new chat. Open the integrations menu and look for
+an entry named `mcp/mcp-docker`. Use the toggle to enable the server:
+
+![LM Studio](images/lm-studio.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param "test_prompt" %}}
+```
+
+### OpenCode
+
+The OpenCode configuration file (at `~/.config/opencode/opencode.json` by
+default) contains the setup for MCP Toolkit:
+
+```json
+{
+  "mcp": {
+    "MCP_DOCKER": {
+      "type": "local",
+      "command": ["docker", "mcp", "gateway", "run"],
+      "enabled": true
+    }
+  },
+  "$schema": "https://opencode.ai/config.json"
+}
+```
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```console
+$ opencode "{{% param "test_prompt" %}}"
+```
+
+### Sema4.ai Studio {#sema4}
+
+In Sema4.ai Studio, select **Actions** in the sidebar, then select the **MCP
+Servers** tab. You should see Docker MCP Toolkit in the list:
+
+![Docker MCP Toolkit in Sema4.ai Studio](./images/sema4-mcp-list.avif)
+
+To use MCP Toolkit with Sema4.ai, add it as an agent action. Find the agent you
+want to connect to the MCP Toolkit and open the agent editor. Select **Add
+Action**, enable Docker MCP Toolkit in the list, then save your agent:
+
+![Editing an agent in Sema4.ai Studio](images/sema4-edit-agent.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param test_prompt %}}
+```
+
+### Visual Studio Code {#vscode}
+
+Open Visual Studio Code. If you configured the MCP Toolkit for a specific
+project, open the relevant project directory. Then open the **Extensions**
+pane. You should see the `MCP_DOCKER` server listed under installed MCP
+servers.
+
+![MCP_DOCKER installed in Visual Studio Code](images/vscode-extensions.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param test_prompt %}}
+```
+
+### Zed
+
+Launch Zed and open agent settings:
+
+![Opening Zed agent settings from command palette](images/zed-cmd-palette.avif)
+
+Ensure that `MCP_DOCKER` is listed and enabled in the MCP Servers section:
+
+![MCP_DOCKER in Zed's agent settings](images/zed-agent-settings.avif)
+
+Test the connection by submitting a prompt that invokes one of your installed
+MCP servers:
+
+```plaintext
+{{% param test_prompt %}}
+```
+
 ## Further reading
 
 - [MCP Toolkit](/manuals/ai/mcp-catalog-and-toolkit/toolkit.md)

data/redirects.yml

@@ -371,4 +371,7 @@
   - /go/dhi-customization/
 
 "/dhi/how-to/customize/#create-an-oci-artifact-image":
-  - /go/dhi-customization-artifacts/
+  - /go/dhi-customization-artifacts/
+
+"/ai/mcp-catalog-and-toolkit/get-started/#verify-connections":
+  - /go/mcp-client-verify/