使用 Docker 构建可落地运行的 AI 系统——基于协议的 AI 集成：使用 MCP

在第 3 章中，你已经学习了如何使用 Docker Model Runner 在本地运行 AI models。这些 models 可以生成文本、回答问题，甚至编写代码。但问题在于：它们无法读取你的文件、查询你的数据库，也无法调用你的 APIs。它们与那些真正能让它们变得有用的 tools 和 data 完全隔离。

想一想：一个能写出完美 SQL queries、却无法连接到你的数据库的 AI，有什么用？或者，一个能生成出色代码、却无法访问你的 GitHub repositories 的 AI，又有什么用？这就像你有一个非常聪明的 assistant，却被锁在一个没有电话、没有互联网、也无法访问你文件的房间里。很令人沮丧，对吧？

这正是 Model Context Protocol（MCP）登场的地方。

MCP 是一种 open standard，它可以将 AI applications 连接到 external systems，而不需要你为每一个 tool 编写 custom integration code。就像 USB-C 给你一个端口，却能同时适配充电器、显示器、外置硬盘和耳机一样，MCP 给你一种协议，却能适配 GitHub、Slack、databases、filesystems，以及数百种其他 tools。Configure it once, use it everywhere。

本章将教你如何使用 Docker 的 integrated solution 部署 MCP servers。你将探索拥有 300 多个 verified servers 的 Docker MCP Catalog，使用 Docker MCP Toolkit 进行 local management，并部署 Docker MCP Gateway 来完成 orchestration。通过 hands-on exercises，你会把 AI 与 GitHub、Firecrawl 和 Postgres 集成起来，让你的 AI applications 真正拥有完成事情的能力。

本章中，你将学习以下内容：

• 理解 Model Context Protocol 及其 core primitives
• Docker 的三部分 MCP solution
• Docker MCP Toolkit 入门
• 为 development 运行 local MCP gateway

Technical requirements

为了跟随本章中的 examples，你需要在自己的机器上设置好以下 tools 和 accounts：

Software

Docker Desktop 4.42.0 或更高版本：MCP Toolkit 从该版本开始内置于 Docker Desktop。你可以从以下地址下载：

https://www.docker.com/products/docker-desktop/

你可以在 terminal 中运行 docker version 来验证版本。

Claude Desktop：本章中，我们使用 Claude Desktop 作为主要 MCP client。下载地址：

https://claude.ai/download

其他受支持的 clients 包括 Cursor、VS Code 和 Windsurf——这些都可以工作，但本章 examples 会引用 Claude Desktop。

Git：用于 clone 本章 code repository。大多数 macOS 和 Linux systems 已经预装 Git。可以用下面命令验证：

git --version

Hardware

至少 8 GB RAM 的机器，推荐 16 GB。MCP servers 以 containers 形式运行，而同时运行多个 servers 和一个 AI client 需要足够 memory。

用于 container images 的 5 GB free disk space。当你启用多个 servers 时，MCP Gateway image 和 individual server images 会很快累积起来。

Accounts and API keys

GitHub account：你需要一个具备 repository access 的 GitHub Personal Access Token（PAT）。可以在以下地址生成：

https://github.com/settings/tokens

至少选择 repo scope。请把这个 token 放在手边——你会在 “Managing secrets securely” section 中使用 Docker 的 secret management 安全存储它。

Firecrawl account（optional） ：如果你想跟随 web search integration examples，请在以下地址注册：

https://www.firecrawl.dev/

并生成一个 API key。它提供 free tier，可用于 testing。

Knowledge prerequisites

本章假设你已经熟悉 basic Docker concepts，包括运行 containers、使用 Docker Compose，以及 working with volumes——这些内容已经在第 1 章和第 2 章中覆盖。熟悉第 3 章中的 Docker Model Runner 会有帮助，但并非严格必要。你还应该能够熟练使用 terminal，并能编辑 YAML configuration files。

本章代码示例可在以下位置获取：

https://github.com/PacktPublishing/Operational-AI-with-Docker/tree/main/chap-06

Understanding the Model Context Protocol

在深入 Docker 的 MCP solution 之前，我们先讨论 MCP 实际上做什么，以及为什么 traditional deployment approaches 会制造你并不需要的麻烦。

What MCP actually does

MCP 定义了三个 core primitives，它们赋予你的 AI 真正的 capabilities：

Tools：这些是你的 AI 可以执行的 actions。想象一个 GitHub MCP server——它可能暴露 create_issue、list_pull_requests 或 search_code 等 tools。当 Claude 需要创建一个 GitHub issue 时，它会通过 MCP 调用这个 tool。就这么简单。

Resources：这些是你的 AI 可以读取和访问的数据。一个 database MCP server 可以把 tables 暴露为 resources，例如 postgres://table/users 或 postgres://table/orders。你的 AI 可以访问这些 resources，而无需编写 SQL queries 或 custom code。

Prompts：这些是用于 complex interactions 的 templates。一个 code review MCP server 可能提供诸如 “Review this pull request for security issues” 或 “Suggest performance optimizations” 这样的 prompts。这些 prompts 会引导 AI 进入你已经定义好的 specialized workflows。

图 6.1 展示了这三个 primitives 如何在整体 MCP architecture 中组合在一起。在左侧，user 将一个 prompt 提交给 MCP Host，MCP Host 中包含一个或多个 MCP Clients。每个 client 都会通过 standardized request-response cycle 与 MCP Server 通信。Server 随后连接到 external systems——databases、web servers、data sources 和 local files。在底部，你可以看到 MCP capabilities 的完整集合：notifications、sampling、tools、resources 和 prompts。正是这个 architecture，让 “configure once, use everywhere” 的承诺成为可能。

图 6.1：MCP architecture——clients 通过 standardized protocol 与 servers 通信，使 AI applications 能够跨 external systems 访问 tools、resources 和 prompts

MCP architecture 的强大之处在于：你只需要配置 MCP servers 一次，每一个 MCP client 就可以立即使用它们。无需在不同 AI tools 中重复配置。无需在五个不同 config files 中维护同一套 credentials。也不用追踪哪个 version 能和哪个 client 配合工作。配置一次，就完成了。

所以，MCP 听起来像梦想一样，对吧？一种协议，就能把你的 AI 连接到它需要的一切。它确实如此——设计优雅，承诺也真实。但伟大的想法往往都有现实世界的 deployment challenges。协议本身很稳固，但真正让 MCP servers 在团队范围内运行起来、配置好并确保安全？事情很快就会变得混乱。好消息是，由于 MCP 的 foundations 足够扎实，这些问题完全可以解决，而且 Docker 已经解决了它们。但在直接跳到 solution 之前，我们先走一遍 traditional way 部署 MCP 时会遇到的四个 pain points。理解这些问题，会让你真正明白 Docker 的 approach 为什么重要。

The critical problems with traditional MCP deployment

我们需要坦诚地说：traditional MCP deployment 会制造四个 operational challenges，一旦你试图从少数几个 servers 扩展出去，这些问题会让你想把 laptop 扔出窗外。Docker 的 solution 解决了所有这些问题，但首先，让我展示你会面对什么，这样你才能理解为什么 Docker 的 approach 很重要。

为了理解这些问题为什么重要，请看图 6.2。左边是 traditional MCP deployment：每个 AI client——Claude、VS Code、Cursor——都直接连接到每个 MCP server。结果是一张纠缠在一起的 point-to-point connections 网，每条连接都有自己的 configuration、credentials 和 failure modes。右边是 Docker 的 approach：所有 clients 都通过一个 single MCP Gateway 路由，而这个 Gateway 背后有一个 secure Secret Store。可用的还是同样四个 servers，但 complexity 被折叠成一个 clean、manageable 的 architecture。

图 6.2：Traditional MCP deployment（左）会在 clients 与 servers 之间制造一张复杂的 direct connections 网，而 Docker MCP Gateway（右）通过 single orchestration layer 将 routing、security 和 credential management 集中起来

图 6.2 左边那团 tangled structure 并不只是难看的 diagram；它是一种 daily operational reality。让我们拆解它造成的四个具体问题，从最直接的问题开始：逐个管理所有 servers。

Problem #1: Fragmented server management

每个 MCP server 都作为一个 separate process 运行，有自己的 runtime requirements、configuration format 和 lifecycle management。我来展示这在实践中是什么样子。

假设你需要 filesystem access、database connectivity 和 GitHub integration。听起来很简单，对吧？错。

对于 filesystem server，你首先需要在机器上安装 Node.js 18 或更高版本。然后打开 terminal 并运行：

# Terminal 1: File system server
npx @modelcontextprotocol/server-filesystem $HOME

让我们拆解这个 command 做了什么。npx command 会运行一个 Node.js package，而不需要将它全局安装。@modelcontextprotocol/server-filesystem 是 MCP filesystem server 的 package name。$HOME environment variable 会展开为你的 home directory path，例如 macOS 上的 /Users/username 或 Linux 上的 /home/username。如果你指定了一个不存在的 directory，server 会失败并报出类似下面的错误：

ENOENT: no such file or directory

因此，你会看到如下 output，它确认 server 已成功启动：

Secure MCP Filesystem Server running on stdio

如果你想改为提供对当前 working directory 的访问：

npx @modelcontextprotocol/server-filesystem .

句点（.）表示 current directory。很好！你现在有 filesystem access 了。第一个完成了。但等等，你还需要 database access。

对于 database access，每种 database system（PostgreSQL、MySQL、MongoDB、Redis）都需要自己的 MCP server package，而且 installation methods、configuration formats 和 connection requirements 都不一样。有些 databases 有通过 package managers 可用的 official MCP servers，而另一些则需要 custom implementations 或 third-party packages。

挑战在于：你需要发现适用于自己数据库的 MCP server 是哪个，找到正确 package name，理解它独有的 configuration format，并且独立管理它的 lifecycle。每个 database connection 都会变成另一个 separate process，而你必须手动 monitor 和 restart 它。

对于 GitHub integration，通常你会使用 Docker 的 MCP Toolkit（我们会在下一节探索），或者运行一个 custom Node.js implementation。关键挑战是：这些 servers 中的每一个都独立运行，有自己的 process、configuration 和 error handling。

每个 server 都运行在单独的 terminal window 或 background process 中。当任何 server crash——它们确实会 crash——你必须：

• 注意到 failure（通常是尝试使用它并收到 error 时才发现）
• 记住带有所有 parameters 的 exact command
• Navigate 到正确 directory
• 手动 restart server

你还需要确保每个 runtime 都安装了正确 version。这个需要 Node.js 18。那个需要 Python 3.11。另一个需要 Go 1.21。当你有五个、十个或二十个不同 MCP servers 时，这种 operational complexity 会变得彻底压垮人。

一个 missing environment variable 就会破坏你的 AI workflow。一个 incorrect path 会让 server crash。一个 version mismatch 会造成 silent failures，并花费数小时 debug。非常消耗人。

Problem #2: Client configuration complexity

真正令人烦躁的地方来了。对于完全相同的 MCP servers，每个 MCP client 都需要自己的、完全不同的 configuration format。

对于 VS Code，你需要编辑 settings.json：

// VS Code settings.json
{
  "mcp.servers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

这个 JSON configuration 告诉 VS Code 如何启动 filesystem MCP server。command field 指定要运行的 program（npx）。args array 包含传递给该 program 的 arguments。最后的句点（.）表示 current directory。

看起来够简单。但问题在于——你不能直接把这个 configuration copy 到其他 tools 中。每个 MCP client 都是独立构建的，clients 之间并没有统一的 shared standard 来存储它们的 MCP server settings。所以，即使你想在 Cursor 中运行完全相同的 filesystem server，也必须打开一个完全不同的 file（mcp.json，而不是 settings.json），然后写一个看起来差不多但其实不完全相同的配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

你发现区别了吗？仔细看。Cursor 使用 mcpServers（复数，没有 dot），而 VS Code 使用 mcp.servers（带 dot）。这个 tiny difference 意味着你绝对不能在 tools 之间直接复制 configuration。你试图把 VS Code config 粘贴到 Cursor，结果什么都不工作。也没有 error message 解释为什么。它只是 silently fails。

你可能会觉得这只是 Cursor 的 one-off problem。那我们再试一个 client——Claude Desktop，也就是 non-IDE use cases 中最常见的 MCP client。你需要编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

即使你想要相同 functionality，也必须维护三个 separate configuration files，它们拥有不同 syntax 和 property names。每当你添加一个 new MCP server 或更新 credentials，就必须记得更新所有三个 configurations。Configuration drift 会变得不可避免。你的 filesystem tools 在 VS Code 中能工作，却在 Cursor 中失败，因为你忘了更新那个 configuration file。

Problem #3: Secrets in environment variables

Traditional MCP deployment 会把 credentials 暴露在 process environments 中。你会把 sensitive information 作为 environment variables export 出来：

export DATABASE_URL="postgresql://user:secret123@db:5432/mydb"
export GITHUB_TOKEN="ghp_extremely_secret_token_here"
export OPENAI_API_KEY="sk-very_secret_openai_key"

让我拆解一下这些是什么。export command 会让 variables 对你随后运行的 programs 可用。DATABASE_URL 包含 database connection string，其中包括 username user 和 password secret123。GITHUB_TOKEN 存储你的 GitHub Personal Access Token，它以 ghp_ 开头。OPENAI_API_KEY 保存你的 OpenAI API key，它以 sk- 开头。

这些 secrets 会出现在多个危险位置。当你运行 docker ps -a 时，container environment 会变得可见。当你运行 ps aux | grep mcp 时，process list 会显示 environment variables。当你运行 docker inspect container_id 时，完整 environment 会被暴露出来。

这些 secrets 会出现在 system logs 中；如果你不小心，它们可能被 copy 到 Docker images 里；也可能出现在 error messages 和 stack traces 中；任何能列出 running processes 的 user 或 process 都可以看到它们。

如果你不小心在 shared terminal、screen sharing session 或 CI/CD pipeline 中运行这些 commands，你的 secrets 就会暴露。更糟的是，如果你把这些 export commands 放进 shell script，并不小心 commit 到 version control，那么你的 database passwords 和 API keys 会永久留在 Git history 中。相信我，你不会想向 security team 解释这件事。

Problem #4: OAuth flow management

如果没有 centralized gateway，每个需要 authentication 的 MCP server 都会实现自己的完整 flow。你需要为每个 server 管理 separate credentials：

export FIRECRAWL_API_KEY_1="fc-123abc-server1"
export GITHUB_TOKEN_1="ghp_456def-server1"

export FIRECRAWL_API_KEY_2="fc-789ghi-server2"
export GITHUB_TOKEN_2="ghp_012jkl-server2"

看到那些 numeric suffixes（_1、_2）了吗？每个 server instance 都需要不同 credentials。Server 1 需要自己的 Firecrawl API key 和 GitHub token。Server 2 需要完全独立的 credentials。

有些 servers 使用 configuration files。比如，server 3 的 config.json 可能看起来是这样：

  "firecrawl": {"api_key": "fc-345mno-server3"},
  "github": {"personal_access_token": "ghp_678pqr-server3"}
}

Server 3 把 credentials 存在 file 中，而不是 environment variables 中。

如果你有三个不同 MCP servers 都需要 Firecrawl API access，那么你就需要管理三次 Firecrawl API keys。每个 server 都独立管理自己的 credentials，独立处理 rate limiting，并以不同方式存储 secrets。可能一个 server 把 keys 存在 local files，另一个把 tokens 存在 environment variables，而第三个把 authentication 管理在 database 中。

这四个问题，会把本该简单的 AI tool integration 变成 operational nightmare。Docker 的 MCP solution 通过 containerization、centralized management 和 enterprise-grade security 解决了每一个挑战。

Docker's three-part MCP solution

Docker 通过三个 integrated components 来应对这些 challenges，它们协同工作，使 MCP servers 变得 secure、manageable，并且 production-ready。每个 component 解决 puzzle 的一个不同部分：首先，你需要找到正确的 MCP servers——这就是 Catalog。然后，你需要在自己的机器上运行并配置它们——这就是 Toolkit。最后，你需要在真实世界场景中对它们进行 orchestrate 和 secure——这就是 Gateway。你可以把它看成一个 progression：discover、develop、deploy。我们现在会依次走过每个 component，随后在后续 sections 中 hands-on 使用 Toolkit 和 Gateway。

Docker MCP catalog: Centralized discovery

Docker MCP Catalog 提供一个 trusted hub，用于 discover 和 access verified MCP servers，并无缝集成到 Docker Hub。如今，catalog 收录了来自 leading companies 的 300 多个 verified tools，包括 Google、GitHub、Slack、Atlassian、Notion、GitLab、Shopify、Grafana 和 Pulumi。

你可以在以下地址浏览 catalog，找到按 category 组织的 ready-to-run MCP servers：

https://hub.docker.com/catalogs/mcp

每个 server 都具备 publisher verification、versioned releases，并通过 Docker 经过验证的 pull-based infrastructure 分发。你不再需要在分散的 GitHub repositories、blog posts 和 community lists 中搜索，并猜测哪些 tools 是 trustworthy 的；你只需一次点击，就可以访问一个 verified servers 的 curated collection。

Docker MCP toolkit: Local management

Docker MCP Toolkit 通过内置在 Docker Desktop 中的 CLI 和 visual interface，让 MCP servers 在你的 local machine 上运行起来。从 Docker Desktop 4.42.0 开始，docker mcp command 提供 comprehensive management capabilities。

Toolkit 支持从 Docker Desktop 一键启动 servers；无缝连接到 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 和 continue.dev 等 AI clients；内置 OAuth credential management，并支持 easy revocation；还提供 Gateway server，用于动态向 compatible clients 暴露 enabled tools。通过 built-in memory、network 和 disk isolation，security 默认就被提供。

Docker MCP gateway: Production orchestration

Docker MCP Gateway 是 production MCP deployments 的 central nervous system。它作为 containerized service（docker/mcp-gateway）运行，将多个 MCP servers 聚合为一个 unified、secure endpoint，AI clients 会连接到该 endpoint。

Gateway 提供三项 core capabilities：

Secure by Default：每个 MCP server 都运行在一个 isolated container 中，并拥有 minimal privileges、network restrictions 和 resource limits。这种 container-first approach 确保即使某个 tool 被攻破，也无法破坏 host system 或访问 unauthorized resources。Gateway 会对所有 server images 实施 signature verification，确保只有 trusted containers 会运行。

Unified Management：一个 single gateway endpoint 会聚合多个 MCP servers，并提供 centralized configuration、credential management 和 access control。Organizations 可以从一个地方对所有 AI tools 执行 consistent security policies。AI clients 不需要管理几十个 individual server connections，而是只连接到一个 gateway。

Enterprise Control：Comprehensive logging、monitoring 和 filtering 让 organizations 对 AI tool usage 拥有完整 visibility 和 control。Gateway 支持三种 transport protocols：用于 local development 的 stdio，用于 web applications 的 sse（Server-Sent Events），以及用于 high-throughput scenarios 的 streaming。它包含 prompt interception，用于防止 secret leaks；container-level network isolation，用于限制 MCP servers 未授权 outbound calls；以及 on-demand container lifecycle management，用于在每次 tool call 时生成一个 new container，并在完成后自动 tear it down。三个 components 合在一起，将 fragmented MCP deployment 转换为 enterprise-grade platform。总结来说：Catalog 提供 discovery，Toolkit 支持 local development，Gateway 交付 production security 和 scalability。

在深入 setup 之前，我们先把点连接起来。还记得刚才走过的四个问题吗？下面是 Docker 三个 components 如何逐一消除这些问题。Fragmented server management？Catalog 提供一个发现 verified servers 的 single place，Toolkit 则把它们作为 isolated containers 启动——不再 juggling runtimes 和 terminal windows。Client configuration complexity？Gateway 提供一个 endpoint，所有 clients 都连接到它，因此你只需要配置 servers 一次，而不是编辑三个不同 JSON files。Secrets in environment variables？Toolkit 将 credentials 存储在 Docker encrypted secret store 中，Gateway 在 runtime 注入它们——它们永远不会出现在 environment variables、logs 或 process lists 中。OAuth flow management？Toolkit 集中处理 OAuth flows，Gateway 在 servers 之间共享 authenticated sessions，所以每个 credential 只需要管理一次。现在我们来看它们如何实际运行。

Getting started with Docker MCP toolkit

现在你已经理解 Catalog、Toolkit 和 Gateway 做什么，以及它们如何映射到前面识别的问题，是时候动手了。我们从 Docker MCP Toolkit 开始，因为它是其他一切的基础。Catalog 是你发现 servers 的地方，但 Toolkit 是你实际运行它们的方式。Toolkit 工作后，后面连接 Gateway 就会很直接。本节中，你将安装 Toolkit，从 command line 探索 catalog，启用你的 first MCP servers，安全存储 secrets，并连接 Claude Desktop 等 AI clients。到本节结束时，你将在 local machine 上拥有一个完整可用的 MCP setup。

Installation and setup

Docker MCP Toolkit 从 Docker Desktop 4.42.0 开始内置，因此没有 separate download 或 installation step。如果你已经有较新的 Docker Desktop，就可以直接开始。如果没有，请从以下地址下载：

https://www.docker.com/products/docker-desktop/

并按照你的 operating system 的 installer instructions 操作。要验证版本，可以打开 Docker Desktop 并导航到 Settings > About，或者在 terminal 中运行：

docker version

你需要 4.42.0 或更高版本——如果你使用的是旧版本，请通过 Docker Desktop UI 更新，或从上面的链接下载 latest release。

图 6.3 展示了 About screen，其中显示 version 4.55.0，该版本包含完整 MCP Toolkit support。

图 6.3：Docker Desktop About screen，展示 version 和 component details——继续之前请确认你运行的是 4.42.0 或更高版本

Docker Desktop 安装并验证后，启用 MCP Toolkit 只需要两个步骤：首先，在 Docker Desktop settings 中打开 feature；然后，验证 CLI 在 terminal 中可用。之后，我们会探索 catalog、启用一些 MCP servers、配置 secrets，并连接你的 first AI client。我们先从启用 feature 开始。

Step 1: Enable MCP toolkit

要启用 MCP Toolkit feature，请在 Docker Desktop 中完成以下四个步骤：

1. 打开 Docker Desktop，并点击 gear icon 进入 Settings。
2. 在左侧 sidebar 中向下滚动，选择 Beta features。
3. 勾选 Enable Docker MCP Toolkit 旁边的 checkbox。
4. 点击 Apply & restart 保存更改。

图 6.4：在 Docker Desktop Settings 中启用 Docker MCP Toolkit——导航到 Beta features，并勾选 Enable Docker MCP Toolkit option

Toolkit 现在已经集成进 Docker Desktop。Docker Desktop restart 之后，docker mcp command 会在 terminal 中可用。继续之前，我们先确认一切正常。

Step 2: Verify the CLI

通过运行 help command，确认 docker mcp CLI 可用：

docker mcp --help

这个 command 会显示 docker mcp command 的 help information。--help flag 会展示所有 available subcommands 和 options。

你应该会看到包含 available commands 的 output，包括 catalog、client、config、feature、gateway、policy、secret、server、tools 和 version。每个 command 管理 MCP 的不同方面。

docker mcp --help

Docker MCP Toolkit's CLI - Manage your MCP servers and clients.

Usage: docker mcp [OPTIONS]

Flags:
  -v, --version   Print version information and quit

Available Commands:
  catalog     Manage MCP server catalogs
  client      Manage MCP clients
  config      Manage the configuration
  feature     Manage experimental features
  gateway     Manage the MCP Server gateway
  policy      Manage secret policies
  secret      Manage secrets
  server      Manage servers
  tools       Manage tools
  version     Show the version information

检查 installed version：

docker mcp -v

-v flag 是 --version 的缩写。它会显示 installed version number 和对应 commit hash，看起来像这样：

v1.2.3 (abc123def456)

Version number 告诉你当前 release。Commit hash 标识 exact code version。

在本书写作时，版本是 v0.40.3。到这里，你已经在 Docker Desktop 中启用了 MCP Toolkit，并确认 CLI 正常工作。Tools 已经安装好了——现在看看你可以用它做什么。大多数人首先想知道的是：到底有哪些 MCP servers 可用？这就是 catalog 发挥作用的地方。

Step 3: Explore the catalog

CLI 正常后，你现在可以浏览可用的 MCP servers。查看系统中 configured catalogs：

docker mcp catalog ls

catalog ls subcommand 会列出你已经配置的所有 MCP catalogs。默认情况下，你会看到 mcp/docker-mcp-catalog:latest catalog，也就是 Docker 的 official MCP catalog。

查看 catalog 中的所有 servers：

mcp/docker-mcp-catalog:latest | 1f11ec3844392ee73bdb76ec2ebe376a0874a0f6bbcac5b96e727ba769abcf24 | Docker MCP Catalog

查看 specific catalog server content：

docker mcp catalog show mcp/docker-mcp-catalog

catalog show command 会显示某个 specific catalog 的内容。mcp/docker-mcp-catalog:latest argument 指定要显示哪个 catalog。写作时，总共有 313 个 MCP servers。

你也可以使用 Docker dashboard 访问 catalog，如下所示。

图 6.5：Docker Dashboard 中的 MCP Catalog——可以从 Catalog tab 中直观地 browse、search 和 enable servers

正如图 6.5 所示，catalog 包含来自主要 platforms 和 services 的 servers：AWS、Brave Search、Docker Hub、Elasticsearch、GitHub、MongoDB、Notion、Playwright、Stripe 等。每张 card 都展示 server name、brief description 和 quick-add button。你可以按 name 搜索，也可以按 category 浏览。无论你需要 database access、web scraping、cloud APIs，还是 developer tools，大概率已经有一个 verified server 在等你。

Visual catalog 非常适合探索，但 browsing 并不会真正改变你的 machine 上任何东西。你的 local MCP setup 仍然是空的——有 300 多个 servers 可用，但启用的数量是 0。我们来修复它。

Step 4: Enable your first MCP server

在添加 servers 之前，你需要创建一个 profile。Profile 是一组 named MCP servers，它们可以一起连接到 AI clients。运行以下 command 创建你的 first profile：

docker mcp profile create --name dev_tools

如果运行 command 时遇到任何 error，请把 Docker Desktop 更新到 available latest version。

你会看到：

Created profile dev_tools with 0 servers

现在，我们把第一个 MCP server 添加到这个 profile。运行以下 command 添加 GitHub server，用于 repository management：

docker mcp profile server add dev_tools --server catalog://mcp/docker-mcp-catalog/github-official

你会看到：

Added 1 server(s) to profile dev_tools

profile server add command 会向指定 profile 添加一个 MCP server。dev_tools argument 指定使用哪个 profile。--server flag 使用 catalog reference 指定 server，格式如下：

catalog://<catalog>/<server-name>

运行以下 command 列出 profile 中的 servers：

docker mcp profile server ls --filter profile=dev_tools

你会看到如下结果：

PROFILE   | TYPE  | IDENTIFIER
dev_tools | image | github-official

仔细看 output。github-official server 现在已经属于你的 dev_tools profile，但在你提供 authentication credentials 之前，它实际上不能工作。GitHub API 需要 Personal Access Token 或 OAuth 才能访问 repositories、创建 issues，或执行任何有用操作。没有 credentials，server 只是坐在那里，什么都做不了。现在我们配置这些 secrets，让 server 真正可用。

Managing secrets securely

永远不要把 credentials 放进 configuration files。如果你在 YAML 或 JSON configs 中 hardcode tokens，它们可能会意外 commit 到 version control、出现在 error logs 中，或对任何能访问你 filesystem 的人可见。我们前面在 Problem #3 中已经覆盖了这些 risks——environment variables 和 config files 中暴露 secrets 是 security nightmare。Docker 的 secure secret management 通过将 credentials 存储在 encrypted store 中来解决这个问题，只有 authorized containers 可以在 runtime 访问它们。

推荐的 secret 存储方式是通过 Docker Desktop UI。这可以避免 credentials 出现在 bash history 中。在 Docker Desktop 中，导航到 MCP Toolkit，选择你的 server，然后在 Configuration tab 中输入 credentials。图 6.6 展示了 GitHub Official server configuration screen，在这里你可以在 Personal Access Token 和 OAuth authentication 之间选择。

如果你更喜欢 CLI，最安全的 approach 是从 file pipe secret，而不是直接输入，因为直接输入会留下 bash history：

echo your_github_pat_here > token.txt
cat token.txt | docker mcp secret set github.personal_access_token
rm token.txt

你可以随时通过以下 command 验证已经存储的 secrets：

docker mcp secret ls

你会看到类似这样的 output：

docker/mcp/github.personal_access_token | docker-pass

这个 command 会列出 secret names 和它们的 storage backend（docker-pass 表示 local keychain，docker-desktop-mcp-oauth 表示 OAuth tokens）。实际 secret values 永远不会显示，只显示 keys，从而确认 secret 已成功存储。

图 6.6：为 GitHub Official MCP server 配置 authentication——在 Docker Dashboard 中选择 Personal Access Token 或 OAuth

Adding filesystem MCP server

类似地，你可以通过运行下面 command，启用 filesystem MCP server，用于 local file access：

docker mcp profile server add dev_tools --server catalog://mcp/docker-mcp-catalog/filesystem

这会启用 filesystem MCP server，它允许 AI applications 在你指定的 directories 中 read 和 write files。

我们验证两个 servers 都已启用。再次运行 server list command：

PROFILE   | TYPE  | IDENTIFIER
dev_tools | image | filesystem
dev_tools | image | github-official

---

Configuring filesystem paths

Filesystem server 需要知道它可以访问哪些 directories。使用 docker mcp profile config command 来设置 allowed paths：

docker mcp profile config dev_tools --set filesystem.paths='["/Users/username/projects", "/Users/username/documents"]'

请将 /Users/username 替换为你实际的 home directory path。你会看到：

- filesystem.paths=[/Users/username/projects /Users/username/documents]

验证 configuration 已正确保存：

docker mcp profile config dev_tools --get-all

Output：

filesystem.paths=[/Users/username/projects /Users/username/documents]

这会把 filesystem server 限制为只能访问这些 specific directories。Server 不能访问你系统上的其他 files 或 directories。

你已经有了 GitHub 用于 repository access，也有 filesystem 用于 local files。但如果你的 AI 需要 search the web，或者 scrape websites 中的 content 呢？这就是 Firecrawl 登场的地方。

---

Adding Firecrawl MCP server

Firecrawl 赋予你的 AI search the web、scrape webpage content，以及从 URLs 中 extract structured data 的能力。当你的 AI 需要 research current information、从 documentation sites 拉取 data，或收集不在它 training data 中的 content 时，这非常有用。使用下面 command 启用它：

docker mcp profile server add dev_tools --server catalog://mcp/docker-mcp-catalog/firecrawl

和 GitHub server 一样，Firecrawl 需要 API key 才能工作。使用 STDIN approach，避免 key 出现在 bash history 中：

echo "fc-your_api_key_here" > firecrawl_key.txt
cat firecrawl_key.txt | docker mcp secret set firecrawl.api_key
rm firecrawl_key.txt

Dot notation（firecrawl.api_key）会创建一个 namespaced secret。这有助于按 service 组织 secrets。请将 fc-your_api_key_here 替换为你的实际 Firecrawl API key。

验证所有 secrets 都已存储：

docker mcp secret ls

你会看到如下 output：

docker/mcp/github.personal_access_token | docker-pass
docker/mcp/firecrawl.api_key            | docker-pass

验证所有三个 servers 都已在你的 profile 中：

docker mcp profile server ls --filter profile=dev_tools

你会看到如下结果：

PROFILE   | TYPE  | IDENTIFIER
dev_tools | image | filesystem
dev_tools | image | firecrawl
dev_tools | image | github-official

验证你的 filesystem configuration 仍然存在：

docker mcp profile config dev_tools --get-all

你不必只依赖 CLI 来查看这些信息。Docker Desktop 也提供了同样的 visual view。图 6.7 展示了 dev_tools MCP Profile tab，在这里你可以看到三个 enabled servers，以及每个 server 提供的 tools 数量。

图 6.7：Docker Desktop 中的 MCP Profile dev_tools tab，你可以查看 enabled servers、它们的 tool counts，并快速 manage 或 remove 它们

我们再运行一次 profile server list command，看看目前配置的完整情况：

docker mcp profile server ls --filter profile=dev_tools

PROFILE   | TYPE  | IDENTIFIER    
dev_tools | image | filesystem    
dev_tools | image | firecrawl     
dev_tools | image | github-official

让我们盘点一下你现在处在什么位置。你已经向 dev_tools profile 添加了三个 MCP servers：GitHub 用于 repository operations，Filesystem 用于 local file access，Firecrawl 用于 web scraping。你已经使用 Docker 的 secret management 安全存储 credentials。三个 servers 都已经 configured 并 ready。但 MCP servers 自己不会做任何事；它们只是等待 requests。你需要一个 AI client，它能发送 prompts、接收 responses，并代表你调用 tools。这就是 missing piece。一旦你连接了 Claude Desktop 这样的 client，你的 AI 就会突然拥有来自这三个 servers 的所有 tools。

Connecting AI clients

为了 leverage MCP servers，你需要一个 AI client。本节中，你会看到如何连接 Claude Desktop 等 AI clients，使它们使用你的 MCP servers。

从以下地址下载 Claude Desktop：

https://claude.com/download

安装完成后，运行以下 command，将 Claude Desktop 连接到你的 dev_tools profile：

docker mcp client connect claude-desktop --profile dev_tools --global

client connect command 会配置某个 AI client，使其使用 Docker MCP。claude-desktop argument 指定要配置哪个 client。--profile dev_tools flag 告诉 Gateway 向该 client 暴露哪些 servers。--global flag 会将 configuration 应用于 system-wide，而不是某个 specific project directory。

你会看到如下结果：

=== System-wide MCP Configurations ===
 ● claude-desktop: connected
   MCP_DOCKER: Docker MCP Catalog (gateway server) (stdio)
 You might have to restart 'claude-desktop'.

你的 client 现在已经连接！可以使用以下 command 查看 available tools：

docker mcp tools ls

或者，你也可以通过选择 Clients 并点击 Connect 来启用 Claude Desktop，如下图所示：

图 6.8：Docker Desktop 中的 MCP Toolkit Clients tab，点击 Claude Desktop 旁边的 Connect 来配置 integration

运行这个 command 后，restart Claude Desktop。Configuration changes 会在 application restart 后生效。

重启 Claude Desktop 后，你会看到 MCP integration 已经 active。点击 chat interface 中的 + button 查看 available options。你现在应该能在 menu 中看到 Add from MCP_DOCKER，如图 6.9 所示。这确认 Claude Desktop 已成功连接 Docker MCP，并且可以访问你启用的 servers。

图 6.9：带有 MCP_DOCKER integration 的 Claude Desktop——menu 中出现 Add from MCP_DOCKER option，让你可以访问 AssignCodingAgent、Issue to fix workflow 和 mcp-discover 等 tools

在 Claude interface 中，在 integrations 或 settings 下找到 MCP_DOCKER。点击 Connectors 查看 tools list。

图 6.10：Claude Desktop 下 available Docker MCP tools 列表

你会看到类似以下的 available tools：

filesystem.read_file
filesystem.list_directory
filesystem.write_file
github.list_repositories
github.create_issue
github.search_code
firecrawl.web_search
firecrawl.scrape_url

通过向 Claude 提一个问题来测试 connection：

List the files in my projects directory

Claude 会自动调用 filesystem.list_directory tool，并显示你的 files。你不需要写任何 code，也不需要配置任何 paths。MCP Gateway 会处理一切。

图 6.11：在 Claude Desktop 中测试 MCP connection——询问 “List the files in my projects directory” 会触发 filesystem.list_directory tool，并在一步中返回 directory contents

以同样方式连接其他 supported clients。对于 Cursor IDE：

docker mcp client connect cursor --profile dev_tools --global

对于 VS Code：

docker mcp client connect vscode --profile dev_tools --global

如果你希望 system-wide connections 在所有 projects 中持续生效，请添加 --global flag：

docker mcp client connect --profile dev_tools --global claude-desktop

这会创建 system-wide configuration，而不是 project-specific configuration。Connection 会在你的所有 projects 中自动工作。

列出 configured clients，查看它们的 status：

docker mcp client ls --global

client ls command 会列出 AI client connections。--global flag 显示 global（system-wide）connections。

Output 会显示每个 client 的 connection status：

=== System-wide MCP Configurations ===
 ● claude-desktop: connected
   MCP_DOCKER: Docker MCP Catalog (gateway server) (stdio)
 ● cursor: connected
   MCP_DOCKER: Docker MCP Catalog (gateway server) (stdio)
 ● vscode: connected

Filled circle（●）表示该 client 是 known。Status 显示它是 connected 还是 disconnected。Connected clients 会显示它们使用的 transport（这里是 stdio）。

当不再需要某个 client 时，可以 disconnect：

docker mcp client disconnect cursor --global

client disconnect command 会从 client 中移除 MCP configuration。cursor argument 指定要 disconnect 哪个 client。

你会看到最终 output：

=== System-wide MCP Configurations ===
● claude-desktop: connected
   MCP_DOCKER: Docker MCP Catalog (gateway server) (stdio)
● cursor: disconnected
● vscode: connected
   MCP_DOCKER: Docker MCP Catalog (gateway server) (stdio)

到这里，你已经有了一个完整 MCP setup：servers enabled、secrets configured，并且 AI clients connected。当你使用 Claude Desktop 时，它会基于 prompts 自动 discover 并 call tools。但如果你想在不打开 AI client 的情况下测试某个 tool 呢？如果你正在构建 automation scripts 呢？或者你只是想在放手让 AI 使用之前，准确看看某个 tool 做什么呢？这时候 direct CLI access 就很方便。

Working with tools directly

Toolkit 通过 CLI 提供对 MCP tools 的 direct access。要查看当前 session 中可用的 built-in gateway management tools：

docker mcp tools ls

你会看到如下结果：

8 tools:
- code-mode - Create a JavaScript-enabled tool that combines multiple MCP server tools.
- mcp-activate-profile - Activate a saved profile by loading its servers into the current gateway.
- mcp-add - Add a new MCP server to the session.
- mcp-config-set - Set configuration for an MCP server.
- mcp-create-profile - Create or update a profile with the current gateway state.
- mcp-exec - Execute a tool that exists in the current session.
- mcp-find - Find MCP servers in the current catalog by name, title, or description.
- mcp-remove - Remove an MCP server from the registry and reload the configuration.

如果你想查看 profile servers 实际暴露的 tools，请用你的 profile 启动 gateway：

docker mcp gateway run --profile dev_tools

Gateway startup output 会清楚显示每个 server 有哪些 tools：

Those servers are enabled: github-official, filesystem, firecrawl
 > github-official: (41 tools) (2 prompts) (5 resourceTemplates)
 > filesystem: (11 tools)
 > firecrawl: (14 tools)

这意味着你的三个 servers 总共有 66 个 tools。要 inspect 某个 specific built-in tool：

docker mcp tools inspect mcp-find

你会看到如下结果：

Name: mcp-find
Description: Find MCP servers in the current catalog by name, title, or description.
If the user is looking for new capabilities, use this tool to search the MCP catalog
for servers that should potentially be enabled.
Input schema: Complex schema (detailed inspection not yet implemented)

到目前为止，你做的一切都是通过 Docker Desktop 内置 MCP Toolkit 完成的。你创建了 profile、添加了 servers、存储了 secrets，并连接了 clients——所有这些都使用 docker mcp commands 和 Docker Desktop UI。这对你自己的机器上的 local development 非常完美。但如果你需要把 MCP setup 分享给 teammates 呢？或者把它部署到 server 上？或者在没有 Docker Desktop 的 environment 中运行它？这就是 standalone MCP Gateway 登场的地方。本节中，你将学习如何使用 Docker Compose 将 Gateway 作为 containerized service 运行，从而完全控制你的 MCP infrastructure，并能在任何运行 Docker 的地方部署它。

Running the local MCP gateway for development

Docker MCP Gateway 是一个 open-source solution，专门用于 orchestrate 和 manage MCP servers。它充当 AI applications（clients）和它们需要访问的 tools（servers）之间的 centralized proxy，处理 server lifecycle、routing 和 authentication。

接下来几页，你会创建一个用于 Gateway 的 Docker Compose configuration，理解每个 configuration option，作为 background service 运行 Gateway，并验证它是否正常工作。我们从 Compose file 开始，因为 magic 都发生在那里——它定义要运行哪些 servers、如何处理 secrets，以及使用什么 transport protocol。

在创建 Compose file 之前，有一个重要 prerequisite。当把 Gateway 作为 container 运行时，它会直接从 ~/.docker/mcp/config.yaml 读取 filesystem paths，而不是从 profile database 读取。如果你前面已经用 docker mcp profile config 配置了 filesystem paths，需要先将该 configuration export 到 config.yaml：

docker mcp profile config dev_tools --get-all --format yaml

你会看到如下结果：

filesystem.paths:
    - /Users/username/projects
    - /Users/username/documents

请将 /Users/username 替换为你的实际 home directory path。验证它已经正确写入：

cat ~/.docker/mcp/config.yaml

Output 会像这样：

filesystem:
  paths:
    - /Users/username/projects
    - /Users/username/documents

现在，创建一个名为 docker-compose.yaml 的 file：

services:
  gateway:
    image: docker/mcp-gateway
    ports:
      - "8080:8080"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "${HOME}/.docker/mcp:/mcp"
      - "${HOME}/projects:${HOME}/projects"
      - "${HOME}/documents:${HOME}/documents"
    command:
      - --servers=github-official,filesystem,firecrawl
      - --secrets=docker-desktop:/run/secrets/mcp_secret
      - --transport=sse
      - --port=8080
      - --verify-signatures
      - --block-secrets
      - --log-calls
      - --additional-config=/mcp/config.yaml
    secrets:
      - mcp_secret

secrets:
  mcp_secret:
    file: .env

让我们逐行看 Docker MCP Gateway configuration：

services: line 开始 services section。Services 是 Docker Compose 管理的 containers。

gateway: line 创建一个名为 gateway 的 service。image: docker/mcp-gateway line 指定使用 Docker Hub 上哪个 container image。

ports: section 将 container ports 映射到 host ports。"8080:8080" mapping 让 Gateway 可以通过 host machine 的 8080 端口访问。

volumes: section 将 directories mount 到 container 中。/var/run/docker.sock:/var/run/docker.sock line 让 Gateway 能访问 Docker daemon socket，从而启动和管理 MCP server containers。${HOME}/.docker/mcp:/mcp line 将你的 local MCP configuration directory mount 到 container 中。额外两个 volume mounts 让你的 projects 和 documents directories 可以被 container 内的 filesystem server 访问。注意，Docker Compose volume mounts 中不会展开 ~ shorthand——请始终使用 ${HOME}。

command: section 向 container 提供 arguments。--servers=github-official,filesystem,firecrawl argument 指定启用哪些 servers——注意，使用 Docker Compose 时用的是 --servers，而不是 --profile，因为 --profile flag 只在 docker mcp gateway run CLI command 中可用。--secrets=docker-desktop:/run/secrets/mcp_secret argument 告诉 Gateway 从 mounted secret file 中查找 secrets。--transport=sse argument 将 communication protocol 设置为 Server-Sent Events。--port=8080 argument 设置 listening port。--verify-signatures argument 确保只运行 trusted、signed container images。--block-secrets argument 防止 secrets 通过 tool responses 泄漏。--log-calls argument 记录所有 tool calls，用于 visibility 和 auditing。--additional-config=/mcp/config.yaml argument 从 mounted config file 读取 filesystem paths configuration。

Service-level 的 secrets: section 声明这个 service 需要访问名为 mcp_secret 的 secret。Top-level 的 secrets: section 定义 secret content 来自你的 .env file。

创建带有 credentials 的 .env file：

echo "github.personal_access_token=ghp_your_token_here" > .env
echo "firecrawl.api_key=fc_your_key_here" >> .env

永远不要把这个 file commit 到 version control。立即把它添加到 .gitignore：

echo ".env" >> .gitignore

启动 service：

docker compose up -d

-d flag 会让 Gateway 在 detached mode 下作为 background service 运行。你会看到：

[+] Running 2/2
✔ Network mcp-gateway-test_default Created
✔ Container mcp-gateway-test-gateway-1 Started

检查 Gateway status：

docker compose ps

查看 logs，了解 Gateway 正在做什么：

docker compose logs gateway --tail=50

你会看到完整 startup sequence：

Note: dynamic-tools disabled when using --servers flag
- Reading configuration...
  - Reading catalog from [https://desktop.docker.com/mcp/catalog/v3/catalog.yaml]
  - Reading config from /mcp/config.yaml
- Configuration read in 127.701625ms
- Using images:
  - ghcr.io/github/github-mcp-server@sha256:a9dd...
  - mcp/filesystem@sha256:35fcf...
  - mcp/firecrawl@sha256:6d990...
- Those servers are enabled: github-official, filesystem, firecrawl
- filesystem: Secure MCP Filesystem Server running on stdio
- filesystem: Allowed directories: [ '/Users/username/projects', '/Users/username/documents' ]
  > filesystem: (11 tools)
  > github-official: (41 tools) (2 prompts) (5 resourceTemplates)
  > firecrawl: (14 tools)
> 66 tools listed in 5.548609211s
> Initialized in 8.972762796s
> Start sse server on port 8080
> Gateway URL: http://localhost:8080/sse
> Authentication disabled (running in container)

三个 servers 都已成功运行——filesystem 提供 11 个 tools，GitHub 提供 41 个 tools，Firecrawl 提供 14 个 tools，总共 66 个 tools。Gateway 现在可通过以下地址访问：

http://localhost:8080/sse

你可能会在 logs 中看到这个 warning：

Warning: Failed to fetch secrets from secrets engine: Post "http://localhost/resolver.v1.ResolverService/GetSecrets": dial unix /root/.cache/docker-secrets-engine/engine.sock: connect: no such file or directory

这在把 Gateway 作为 container 运行时是 expected 的——Docker Desktop 的 secrets socket 不能从 container 内部访问。Gateway 会 fallback 到从 mounted .env file 中读取 secrets，这也是为什么我们包含了 --secrets=docker-desktop:/run/secrets/mcp_secret flag，指向 mounted secret file。

完成后停止 service：

docker compose down

docker compose down command 会停止并移除所有 services。你的 configuration 会保留在 docker-compose.yaml 中，以便下次使用。

这个 deployment 可以在任何 Docker-compatible environment 中工作，包括没有 Docker Desktop 的 systems。它非常适合 development environments、CI/CD pipelines，或你需要完全控制 MCP infrastructure 的 production deployments。

你现在已经拥有一个 production-ready Gateway deployment，并且它具备 secure secret management，在 single containerized endpoint 后运行 GitHub、filesystem 和 Firecrawl servers。但你的 own data 呢？MCP 最强大的 use cases 之一，就是让 AI applications 访问你的 databases——让它们 query data、generate reports，并回答关于 business 的问题，而不需要你为每个 request 编写 custom code。我们来看它如何工作。

Database integration example

将 MCP 与 database 集成，使 AI applications 获得 data access。这个 example 使用 SQLite：它是轻量级、file-based database，不需要 separate database server，不需要 credentials，并且能在所有 platforms 上工作，包括 Apple Silicon。

Clone repository，并进入 example directory：

git clone https://github.com/PacktPublishing/Operational-AI-with-Docker/
cd Operational-AI-with-Docker/chap-06/local-mcp-gateway-database

compose.yaml 定义了三个 services：

services:
  client:
    build: .
    environment:
      - MCP_HOST=http://gateway:8811/mcp
    depends_on:
      - gateway
    restart: on-failure

  gateway:
    image: docker/mcp-gateway
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command:
      - --transport=streaming
      - --servers=SQLite
      - --port=8811
      - --verbose=false

  db-init:
    image: mcp/sqlite@sha256:efbc05ccace18df122f26b674bd1730c76ece716551df2b3961d519909c34696
    volumes:
      - ./data:/mcp
    entrypoint: ["sh", "-c", "exit 0"]

这个 configuration 包含三个 services：

• gateway service 运行 MCP Gateway。
• client service 构建并运行 Python application，它连接到 Gateway 并执行 database operations。
• db-init service 在 gateway 启动前初始化 SQLite database file。

对于 Gateway，--transport=streaming argument 使用 streaming protocol，以获得更好的 database query performance。--servers=SQLite argument 启用 SQLite MCP server。这里没有指定 --tools flag——所有 6 个 SQLite tools 都可用，以便让 AI applications 拥有完整 database access，包括创建 tables、读取 data 和写入 data。

client service 上的 restart: on-failure policy 会处理 client 启动与 gateway 完全 ready 之间的 timing gap——Docker 会自动 retry client，直到 gateway 可用。

db-init service 会运行 SQLite container，并立即 exit，以确保 database volume 在 gateway 启动之前完成初始化。

main.py 中的 Python client 会连接到 gateway，并执行三个 database operations：

Client 会连接到：

http://gateway:8811/mcp

这是 Gateway 的 streaming endpoint。它会初始化 MCP session，并调用三个 tools。create_table tool 会创建一个包含 id、name 和 price columns 的 products table。write_query tool 会插入三条 product records。read_query tool 会读取所有 records，并以 dictionaries list 的形式返回它们。

Dockerfile 使用 lightweight Alpine base 构建 Python client image：

FROM python:3.13-alpine
RUN pip install mcp[cli]
WORKDIR /app
COPY main.py ./
CMD ["python", "main.py"]

启动 stack：

docker compose up -d

Gateway 第一次运行时，需要大约 10 秒来 pull 和 initialize SQLite container。观察 logs 来查看 startup sequence：

你会看到 gateway 读取 catalog、pull SQLite image、启动 SQLite container，并列出 available tools：

Those servers are enabled: SQLite
Listing MCP tools...
Running mcp/sqlite with [docker run --rm -i ...]
SQLite: (6 tools) (1 prompt) (1 resource) 6 tools listed in 5.582120919s Start streaming server on port 8811 Gateway URL: http://localhost:8811/mcp

Gateway ready 后，client 会自动运行。查看 client output：

sleep 10 && docker compose logs client

你会看到：

client-1  | Table created
client-1  | Data inserted
client-1  | Query result:
client-1  | [{'id': 1, 'name': 'Widget', 'price': 9.99}, {'id': 2, 'name': 'Gadget', 'price': 24.99}, {'id': 3, 'name': 'Doohickey', 'price': 4.99}]

Client 成功创建了 products table，插入了三条 records，并通过 MCP Gateway 读取了它们。你的 AI application 执行了真实 database operations，却没有任何 direct database access——Gateway 处理了 SQLite container 的所有 routing、security 和 lifecycle management。

完成后停止 stack：

docker compose down

Gateway 会通过 SQLite MCP server 执行所有 database operations，并把 results 返回给 client。你的 AI application 可以执行 complex database operations，而无需 direct database access。Gateway 会调解所有 interactions。

Summary

Model Context Protocol 标准化了 AI applications 连接 external tools 和 data sources 的方式。没有 MCP，你需要为每个 AI tool 和每个 data source 编写 custom integration code。有了 MCP，你只需实现协议一次，就可以通过 standardized interfaces 连接到数百个 systems。

Docker 的 MCP solution 由三个 integrated components 组成。Docker MCP Catalog 提供 trusted hub，其中包含来自 leading companies 的 300 多个 verified servers，可通过以下地址访问：

https://hub.docker.com/catalogs/mcp

Docker MCP Toolkit 通过 docker mcp CLI 和 Docker Desktop UI，把 MCP 带到你的 local machine，支持一键 server launches 和 seamless client connections。Docker MCP Gateway 作为 production-ready、containerized orchestration layer，将多个 MCP servers 聚合在一起，并提供 enterprise security。

本章中，你学习了如何使用 docker mcp profile create 和 docker mcp profile server add 创建并管理 profiles；如何使用 catalog references 将 GitHub、filesystem 和 Firecrawl 等 servers 添加到 profile；如何通过 docker mcp secret set 和 Docker Desktop UI，利用 Docker encrypted keychain 安全管理 secrets；如何使用 docker mcp profile config 配置 filesystem paths；以及如何使用 docker mcp client connect --profile --global 连接 Claude Desktop、Claude Code、Cursor 和 VS Code 等 AI clients。

你还学习了如何使用 Docker Compose 和 docker/mcp-gateway image，将 Gateway 作为 containerized service 运行，包括如何正确配置 servers、secrets、transport protocols 和 filesystem paths。你看到，当把 Gateway 作为 container 运行时，必须手动填充 ~/.docker/mcp/config.yaml，因为它无法直接访问 profile database。

最后，你构建了一个完整 database integration example，使用 SQLite 和 MCP Gateway 的 streaming transport，让 Python client 完全通过 Gateway 创建 tables、插入 records 并查询 data，而 application code 没有任何 direct database access。

在第 7 章中，你将构建 autonomous AI agents，它们能够同时 leverage 多个 MCP tools，完成复杂的 multi-step tasks。你会把这里的 Docker MCP infrastructure 与 multi-agent architectures 结合起来，并部署完整的 agentic AI applications。