AI Hub 入门指南（第二部分）：自定义 MCP 服务器
欢迎回到关于 AI Hub 的系列入门文章，这是目前处于早期访问计划（EAP）阶段的新产品功能！（链接：EAP 网站下载、文档）
在上一篇文章中，我们介绍了如何使用新的 %AI 类直接在 ObjectScript 中创建代理和代理工具。 不过，有时您可能并不需要创建新的代理，而只是希望向现有代理添加一些自定义工具，以便让本地 claude、codex、copilot 或其他您选择的代理直接查询您的数据。这时，MCP 服务器就派上用场了。
在本指南中，我们将逐步演示如何创建自己的 MCP 服务器来访问您的数据。
免责声明：AI Hub 目前处于早期访问预览阶段，其功能在正式发布前可能会发生变更；如发现任何问题，可通过上述链接的文档 GitHub 仓库提交问题报告。EAP 预览版不适用于生产环境。
MCP 的简要介绍
我将简要介绍，因为关于 MCP 服务器（模型上下文协议）已有大量其他优质文章（建议从@Pietro Di Leo 的这篇文章或InterSystems 总裁 Don Woodlock 的这段精彩入门视频开始阅读）。
模型上下文协议（Model Context Protocol）是一种传输协议，允许将外部工具添加到代理中。 存在一个发现“握手”过程：MCP 服务器会向 MCP 客户端发送工具列表。工具被发现后，代理即可向 MCP 服务器发送包含参数的工具执行请求，MCP 服务器会执行该工具调用并返回结果。
MCP 服务器可以是远程服务器，即运行在与客户端不同的机器上，这通常使用可流式传输的 http/https 连接或服务器端事件（Server-Side Events）。或者，MCP 服务器也可以是本地服务器，即运行在同一台机器上，通常使用 stdio 连接。
一个重要区别
AI Hub 允许您在 IRIS 环境中创建自定义 MCP 服务器，从而使代理能够访问或监控您的 IRIS 数据库、生产环境及状态。它并非预配置的 MCP 服务器。
如果您正在寻找一款开发工具，旨在让代理能够自由访问 IRIS 环境以加快开发速度，那么您可能需要的是预配置的 MCP 服务器。如果您希望创建安全、可审计且符合 IRIS 受管安全环境的正式生产 MCP 服务器，那么 AI Hub 正是您所需要的。
目前有许多预配置的 MCP 服务器提供用于 IRIS 开发的工具，其中包括由@Thomas Dyar 创建的 MCP 工具和技能库iris-agentic-dev。这是一个与 AI Hub 独立的项目，敬请关注相关文章！
AI Hub 中的 MCP
在上一篇文章中，我们介绍了如何创建代理工具和工具集；本文将详细讲解如何通过 HTTP 和 STDIO 两种方式，将这些工具作为 MCP 服务器进行部署。本文涉及的代码可在 ai-hub-dev-template 中找到，如果您想尝试使用 IRIS AI Hub，这是一个很好的入门起点。
不过在进入正题之前，让我们先来看看 AI Hub MCP 服务器的架构：
MCP 客户端（蓝色）与 iris-mcp-server 通信，以弥合 MCP 调用（发现和执行）与 IRIS 之间的差距。该二进制文件随后通过 %AI.MCP.Service 作为分发类定义的 MCP 服务器 Web 应用程序进行通信。 该分发类随后将工具调用路由至 ObjectScript 工具类，这些工具类进而可对 IRIS 数据库进行操作。此图省略了反向路由（返回工具响应）以及 MCP 客户端与 iris-mcp-server. 之间的初始握手过程
文档中提供了有关此架构的更多详细信息，但此简化视图涵盖了我们需要定义的关键要素。这些要素包括： 1. 工具 / 工具集 2. %AI.MCP.Service 分发类 3. MCP 应用程序 4. iris-mcp-server 配置 5. MCP 客户端连接
让我们逐一了解这些内容。
1. 工具
我们通过继承 %AI.Tool 或 %AI.ToolSet 来定义工具或工具集，这在第 1 部分中已详细介绍，因此我将略过这一部分。
2. 定义分发类
要定义 MCP 服务分派类，我们只需继承 %AI.MCP.Service，并在 SPECIFICATION 参数中指定要包含的工具或工具集：
Class Sample.MCPService Extends %AI.MCP.Service
{
Parameter SPECIFICATION = "Sample.ToolSet";
}
虽然可以通过以逗号分隔的列表形式添加多个工具/工具集类，但为了简化，这里仅包含一个。
3. 创建 MCP 应用程序
接下来，我们创建一个 MCP 服务器应用程序。与其他 Web 应用程序一样，该应用程序既可以通过管理门户进行管理，也可以通过 Security.Applications 类以编程方式进行管理。在此情况下，管理门户中新增了一个 MCP 服务器管理门户：
但对于在 IRIS 中开发 Web 应用程序的开发人员来说，其余部分都会感觉很熟悉。
关键点在于指定一个端点（例如 /mcp/sample）以及我们之前创建的 MCP 服务类。 这里不展示编程实现方式，但可通过 Security.Applications 完成，只需将 Type 的值设置为 18，即可将其注册到 MCP 服务器菜单中。
此时，您可以在 http://localhost:52773/mcp/sample/v1/services 上查看所提供工具的 JSON 描述。这意味着该服务可被 iris-mcp-server 二进制文件发现，但无法被 mcp 客户端直接发现。
4. iris-mcp-server 配置
iris-mcp-server 二进制文件在运行时需要配置文件，可通过以下命令运行：
iris-mcp-server -c config.toml run
关于该命令的具体用法，我们将在下一节（MCP 客户端）中详细说明，但目前我们将重点放在配置文件上。
编写配置文件时，首先要设置与 IRIS 的连接——这需要网关特权用户的凭据（例如 CSPSystem）、Web 网关使用的超级服务器端口（默认 1972）以及您的 MCP 端点：
[[iris]]
name = "local"
server = { host = "localhost", port = 1972, username = "SuperUser", password = "SYS" }
endpoints = [
{path = "/mcp/sample" }
]
接下来，您需要定义传输方式。这在 [mcp] 代码块中完成。
对于 stdio，您只需设置传输类型：
[mcp]
transport="stdio"
对于 http/https，还需指定主机和端口：
[mcp]
transport = "http"
host = "0.0.0.0"
port = 8080
该端口与管理门户的端口不同，仅用于此 MCP 服务器。 这是一个常见的错误，因为虽然您可以在管理门户端口http://localhost:52773/mcp/sample/v1/services 上找到工具目录，但要实际连接到 MCP 服务器，您必须设置一个不同的端口来与 iris-mcp-server 桥接器进行通信。
身份验证
上文中我们已将Web应用程序设置为“无需身份验证”，但在生产环境中应避免此设置。若要添加身份验证，请先将Web应用程序设置为“密码验证”。您可以在端点中添加用户名和密码，或添加承载令牌：
[[iris]]
name = "local"
server = { host = "localhost", port = 1972, username = "SuperUser", password = "SYS" }
endpoints = [
{path = "/mcp/sample", username="SuperUser" password="SYS" }
]
如果您使用的是 HTTP/HTTPS 连接，也可以选择在此处不进行身份验证，而是通过 MCP 客户端的请求来处理身份验证，这将在下文的“从客户端连接”设置中说明。
其他设置
此处还有大量其他配置选项，例如设置OAuth、使用环境密钥而非硬编码设置、配置日志和遥测，以及启用智能工具发现功能。 如需了解更多详情，请参阅iris-mcp-server 的完整使用指南；但对于基本用法，您只需定义 [[iris]] 和 [mcp] 即可。
5. 从 MCP 客户端连接
添加 MCP 服务器的方法会因您使用的客户端而异，但通常在代理自定义设置的某个位置会有一个添加 MCP 服务器的选项。 例如，要在 GitHub Copilot 上设置 MCP 服务器，请在 VS Code 搜索栏中输入 >MCP: Add Server...；若使用 Claude Code，则可运行 claude mcp add...。
第一个选项通常会在 stdio 和 http(s) 传输方式之间进行选择。由于这两种方式的连接方法差异较大，因此我们将分别进行说明。
stdio
要使用 stdio MCP 服务器，请将 /path/to/iris-mcp-server 作为可执行文件添加。在 Docker 容器中，其默认位置为 /usr/irissys/bin。
你还需要为 stdio 配置文件 config_stdio.toml 和运行命令添加参数：
/usr/irissys/bin/iris-mcp-server -c config_stdio.toml run
由于身份验证信息已包含在配置文件中，因此只需这些设置即可。
请注意，
iris-mcp-server二进制文件必须与您的 MCP 客户端位于同一台机器（或容器）上！
HTTP
若要从 MCP 客户端连接到远程 HTTP MCP 服务器，首先需要通过打开终端并执行以下命令来启动 iris-mcp-server 传输服务：
iris-mcp-server -c config_http.toml run
与 STDIO 连接不同，该传输必须持续运行，HTTP 连接才能正常工作。
该进程运行后，我们即可通过在 MCP 客户端中选择 HTTP 作为传输方式或类型，并输入服务器 URL：http://localhost:8080/mcp/sample，将该服务器添加到 MCP 客户端中。
如果希望在 MCP 连接层级（而非上文所述的配置层级）设置身份验证，则使用标准的 HTTP 身份验证头，例如 Basic base64(Username:Password) 或 Bearer 。 以下 Python 代码片段展示了使用 Langchain 的 MultiServerMCPClient 连接 MCP 服务器的示例：
import base64
from langchain_mcp_adapters.client import MultiServerMCPClient
AUTH_HEADER = base64.b64encode(b"SuperUser:SYS").decode("utf-8")
async def get_tools():
client = MultiServerMCPClient(
{
"minimal": {
"transport": "http",
"url": "http://localhost:8080/mcp/sample",
"headers": {"Authorization": f"Basic {AUTH_HEADER}"},
}
}
)
tools = await client.get_tools()
return tools</code></pre><h1> </h1><h1>结论</h1><p>本系列的第 2 部分到此结束！这一部分内容较长，如果您能坚持看到这里，真是太棒了。希望本指南能让您充满信心，利用 AI Hub 预览版在 IRIS 中开始构建自己的 MCP 服务器，从而为代理提供对您的 IRIS 实例的安全且受管控的访问权限。</p><p>如果您想查看本文中的示例代码，所有内容均包含在 Open Exchange 上的<a href="https://openexchange.intersystems.com/package/ai-hub-dev-template">ai-hub-dev-template</a>项目中。 这是一个示例 Docker 项目，您可以轻松克隆并使用它，在本地机器上开始使用 AI Hub。其中包含一个示例 MCP 服务器，以及用于通过编程方式创建 MCP 服务器 Web 应用程序的示例代码。</p>