docker · aevesdocker · Feb 3, 2025 · Feb 3, 2025 · Feb 3, 2025
diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml
@@ -75,6 +75,7 @@ exceptions:
   - LLDB
   - LTS
   - MAC
+  - MCP
   - MDM
   - MDN
   - MSI

@@ -0,0 +1,142 @@
+---
+title: MCP
+description: Learn how to use MCP servers with Gordon
+keywords: ai, mcp, gordon
+---
+
+## What is MCP?
+
+Anthropic recently announced the [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) (MCP) specification, an open protocol that standardises how applications provide context to large language models. MCP functions as a client-server protocol, where the client (e.g., an application like Gordon) sends requests, and the server processes those requests to deliver the necessary context to the AI.
+
+Gordon, along with other MCP clients like Claude Desktop, can interact with MCP servers running as containers. Docker has partnered with Anthropic to build container images for the [reference implementations](https://github.com/modelcontextprotocol/servers/) of MCP servers, available on Docker Hub under [the mcp namespace](https://hub.docker.com/u/mcp).
+
+## Simple MCP server usage with Gordon
+
+When you run the `docker ai` command in your terminal to ask a question, Gordon looks for a `gordon-mcp.yml` file in your working directory for a list of MCP servers that should be used when in that context. The `gordon-mcp.yml` file is a Docker Compose file that configures MCP servers as Compose services for Gordon to access.
+
+The following minimal example shows how you can use the [mcp-time server](https://hub.docker.com/r/mcp/time) to provide temporal capabilities to Gordon. For more information, you can check out the [source code and documentation](https://github.com/modelcontextprotocol/servers/tree/main/src/time).
+
+1. Create the `gordon-mcp.yml` file and add the time server:
+
+    ```yaml
+    services:
+      time:
+        image: mcp/time
+    ```
+
+2. With this file you can now ask Gordon to tell you the time in another timezone:
+
+    ```bash
+    $ docker ai 'what time is it now in kiribati?'
+
+        • Calling get_current_time
+
+      The current time in Kiribati (Tarawa) is 9:38 PM on January 7, 2025.
+
+    ```
+
+
+As you can see, Gordon found the MCP time server and called its tool when needed.
+
+## Advanced usage
+
+Some MCP servers need access to your filesystem or system environment variables. Docker Compose can help with this. Since `gordon-mcp.yml` is a Compose file you can add bind mounts using the regular Docker Compose syntax, which makes your filesystem resources available to the container:
+
+```yaml
+services:
+  fs:
+    image: mcp/filesystem
+    command:
+      - /rootfs
+    volumes:
+      - .:/rootfs
+```
+
+The `gordon-mcp.yml` file adds filesystem access capabilities to Gordon and since everything runs inside a container Gordon only has access to the directories you specify.
+
+Gordon can handle any number of MCP servers. For example, if you give Gordon access to the internet with the `mcp/fetch` server:
+
+```yaml
+services:
+  fetch:
+    image: mcp/fetch
+  fs:
+    image: mcp/filesystem
+    command:
+      - /rootfs
+    volumes:
+      - .:/rootfs
+```
+
+You can now ask things like:
+
+```bash
+$ docker ai can you fetch rumpl.dev and write the summary to a file test.txt 
+
+    • Calling fetch ✔️
+    • Calling write_file ✔️
+
+  The summary of the website rumpl.dev has been successfully written to the file test.txt in the allowed directory. Let me know if you need further assistance!
+
+
+$ cat test.txt 
+The website rumpl.dev features a variety of blog posts and articles authored by the site owner. Here's a summary of the content:
+
+1. **Wasmio 2023 (March 25, 2023)**: A recap of the WasmIO 2023 conference held in Barcelona. The author shares their experience as a speaker and praises the organizers for a successful event.
+
+2. **Writing a Window Manager in Rust - Part 2 (January 3, 2023)**: The second part of a series on creating a window manager in Rust. This installment focuses on enhancing the functionality to manage windows effectively.
+
+3. **2022 in Review (December 29, 2022)**: A personal and professional recap of the year 2022. The author reflects on the highs and lows of the year, emphasizing professional achievements.
+
+4. **Writing a Window Manager in Rust - Part 1 (December 28, 2022)**: The first part of the series on building a window manager in Rust. The author discusses setting up a Linux machine and the challenges of working with X11 and Rust.
+
+5. **Add docker/docker to your dependencies (May 10, 2020)**: A guide for Go developers on how to use the Docker client library in their projects. The post includes a code snippet demonstrating the integration.
+
+6. **First (October 11, 2019)**: The inaugural post on the blog, featuring a simple "Hello World" program in Go.%   
+
+```
+
+## What’s next?
+
+Now that you’ve learned how to use MCP servers with Gordon, here are a few ways you can get started:
+
+- Experiment: Try integrating one or more of the tested MCP servers into your `gordon-mcp.yml` file and explore their capabilities.
+1. Explore the ecosystem: Check out the [reference implementations on GitHub](https://github.com/modelcontextprotocol/servers/) or browse the [Docker Hub MCP namespace](https://hub.docker.com/u/mcp) for additional servers that might suit your needs.
+2. Build your own: If none of the existing servers meet your needs, or you’re curious about exploring how they work in more detail, consider developing a custom MCP server. Use the [MCP specification](https://www.anthropic.com/news/model-context-protocol) as a guide.
+3. Share your feedback: If you discover new servers that work well with Gordon or encounter issues with existing ones, [share your findings to help improve the ecosystem.](https://docker.qualtrics.com/jfe/form/SV_9tT3kdgXfAa6cWa)
+
+With MCP support, Gordon offers powerful extensibility and flexibility to meet your specific use cases whether you’re adding temporal awareness, file management, or internet access.
+
+### List of known working MCP Servers
+
+These are the MCP servers that have been tested successfully with Gordon:
+
+- `mcp/time`
+- `mcp/fetch`
+- `mcp/filesystem`
+- `mcp/postgres`
+- `mcp/git`
+- `mcp/sqlite`
+- `mcp/github`
+
+### List of untested MCP servers
+
+These are the MCP servers that were not tested but should work if given the appropriate API tokens:
+
+- `mcp/brave-search`
+- `mcp/gdrive`
+- `mcp/slack`
+- `mcp/google-maps`
+- `mcp/gitlab`
+- `mcp/everything`
+- `mcp/aws-kb-retrieval-server`
+- `mcp/sentry`
+
+### List of MCP servers that don’t work with Gordon
+
+These are the MCP servers that are currently unsupported:
+
+- `mcp/sequentialthinking` - The tool description is too long
+- `mcp/puppeteer` - Puppeteer sends back images and Gordon doesn’t know how to handle them, it only handles text responses from tools
+- `mcp/everart` - Everart sends back images and Gordon doesn’t know how to handle them, it only handles text responses from tools
+- `mcp/memory` - There is no way to configure the server to use a custom path for its knowledge base
@@ -20,13 +20,13 @@ The following table provides an overview of the included usage and limits for ea
 user type, subject to fair use:
 
 
-| User type                | Pulls per month | Pull rate limit per hour | Public repositories | Public repository storage | Private repositories | Private repository storage |
-|--------------------------|-----------------|--------------------------|---------------------|---------------------------|----------------------|----------------------------|
-| Business (authenticated) | 1M              | Unlimited                | Unlimited           | Unlimited                 | Unlimited            | Up to 500 GB               |
-| Team (authenticated)     | 100K            | Unlimited                | Unlimited           | Unlimited                 | Unlimited            | Up to 50 GB                |
-| Pro (authenticated)      | 25K             | Unlimited                | Unlimited           | Unlimited                 | Unlimited            | Up to 5 GB                 |
-| Personal (authenticated) | Not applicable  | 40                       | Unlimited           | Unlimited                 | Up to 1              | Up to 2 GB                 |
-| Unauthenticated users    | Not applicable  | 10 per IP address        | Not applicable      | Not applicable            | Not applicable       | Not applicable             |
+| User type                | Pulls per month | Pull rate limit per hour               | Public repositories | Public repository storage | Private repositories | Private repository storage |
+|--------------------------|-----------------|----------------------------------------|---------------------|---------------------------|----------------------|----------------------------|
+| Business (authenticated) | 1M              | Unlimited                              | Unlimited           | Unlimited                 | Unlimited            | Up to 500 GB               |
+| Team (authenticated)     | 100K            | Unlimited                              | Unlimited           | Unlimited                 | Unlimited            | Up to 50 GB                |
+| Pro (authenticated)      | 25K             | Unlimited                              | Unlimited           | Unlimited                 | Unlimited            | Up to 5 GB                 |
+| Personal (authenticated) | Not applicable  | 40                                     | Unlimited           | Unlimited                 | Up to 1              | Up to 2 GB                 |
+| Unauthenticated users    | Not applicable  | 10 per IPv4 address or IPv6 /64 subnet | Not applicable      | Not applicable            | Not applicable       | Not applicable             |
 
 For more details, see the following:
 
@@ -45,10 +45,10 @@ exhibiting excessive data and storage consumption.
 
 Docker Hub has an abuse rate limit to protect the application and
 infrastructure. This limit applies to all requests to Hub properties including
-web pages, APIs, and image pulls. The limit is applied per-IP, and while the
-limit changes over time depending on load and other factors, it's in the order
-of thousands of requests per minute. The abuse limit applies to all users
-equally regardless of account level.
+web pages, APIs, and image pulls. The limit is applied per IPv4 address or per
+IPv6 /64 subnet, and while the limit changes over time depending on load and
+other factors, it's in the order of thousands of requests per minute. The abuse
+limit applies to all users equally regardless of account level.
 
 You can differentiate between the pull rate limit and abuse rate limit by
 looking at the error code. The abuse limit returns a simple `429 Too Many

@@ -23,13 +23,13 @@ The following pull usage and limits apply based on your subscription, subject to
 fair use:
 
 
-| User type                | Pulls per month | Pull rate limit per hour |
-|--------------------------|-----------------|--------------------------|
-| Business (authenticated) | 1M              | Unlimited                |
-| Team (authenticated)     | 100K            | Unlimited                |
-| Pro (authenticated)      | 25K             | Unlimited                |
-| Personal (authenticated) | Not applicable  | 40                       |
-| Unauthenticated Users    | Not applicable  | 10 per IP address        |
+| User type                | Pulls per month | Pull rate limit per hour               |
+|--------------------------|-----------------|----------------------------------------|
+| Business (authenticated) | 1M              | Unlimited                              |
+| Team (authenticated)     | 100K            | Unlimited                              |
+| Pro (authenticated)      | 25K             | Unlimited                              |
+| Personal (authenticated) | Not applicable  | 40                                     |
+| Unauthenticated Users    | Not applicable  | 10 per IPv4 address or IPv6 /64 subnet |
 
 ## Pull definition
 
@@ -121,6 +121,13 @@ for information on authentication.
 
 If you're using any third-party platforms, follow your provider’s instructions on using registry authentication.
 
+> [!NOTE]
+>
+> When pulling images via a third-party platform, the platform may use the same
+> IPv4 address or IPv6 /64 subnet to pull images for multiple users. Even if you
+> are authenticated, pulls attributed to a single IPv4 address or IPv6 /64 subnet
+> may cause [abuse rate limiting](./_index.md#abuse-rate-limit).
+
 - [Artifactory](https://www.jfrog.com/confluence/display/JFROG/Advanced+Settings#AdvancedSettings-RemoteCredentials)
 - [AWS CodeBuild](https://aws.amazon.com/blogs/devops/how-to-use-docker-images-from-a-private-registry-in-aws-codebuild-for-your-build-environment/)
 - [AWS ECS/Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)
@@ -153,7 +160,6 @@ separated file with the following detailed information.
 | `version_checks`     | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors.                                                  |
 | `pulls`              | The number of pulls accumulated for the date and hour of each image repository.                                                                                                                                            | This helps identify the frequency of repository pulls, which you can use to analyze usage trends and potential unexpected behaviors.                                                |
 
-
 ## View hourly pull rate and limit
 
 The pull rate limit is calculated on a per hour basis. There is no pull rate
@@ -215,4 +221,5 @@ To view your current pull rate and limit:
    is unlimited in partnership with a publisher, provider, or an open source
    organization. It could also mean that the user you are pulling as is part of a
    paid Docker plan. Pulling that image won't count toward pull rate limits if you
-   don't see these headers.
+   don't see these headers.
+
@@ -45,7 +45,7 @@ Using the `admin-settings.json` file, you can:
 - Turn off Docker Extensions
 - Turn off Docker Scout SBOM indexing
 - Turn off beta and experimental features
-- Turn off Docker AI ([Ask Gordon](../../../../desktop/features/gordon.md))
+- Turn off Docker AI ([Ask Gordon](../../../../desktop/features/gordon/_index.md))
 - Turn off Docker Desktop's onboarding survey
 - Control whether developers can use the Docker terminal
 - Control the file sharing implementation for your developers on macOS
-Original file line number
+Diff line change
@@ Expand Up / @@ -75,6 +75,7 @@ exceptions: @@
       - LLDB
       - LTS
       - MAC
+      - MCP
       - MDM
       - MDN
       - MSI
@@ Expand Down @@