[]
帮助文档 视频教程 API文档 开发者社区 认证体系 应用和插件市场
V 11.1
立即下载
(Showing Draft Content)

活字格应用作为MCP客户端

配置和使用 MCP 服务器（作为客户端）

本文档旨在说明如何在活字格中配置和使用 MCP 服务器，以扩展 AI 功能。通过将活字格作为 MCP 客户端，你可以连接到外部的 AI 工具和服务。

一、核心概念

在配置前，了解几种常见的 MCP 服务器连接模式会有所帮助：

  • StreamableHTTP / SSE 模式：这两种模式用于连接通过网络 URL 访问的 MCP 服务器，如阿里云百炼、火山引擎等云服务商提供的工具。SSE 是 HTTP 的一种特殊形式，支持服务器流式返回数据。

  • Stdio 模式：此模式用于调用本地计算机上运行的命令行程序。例如，你可以将一个本地的文件处理脚本封装为 MCP 工具供 AI 调用。

二、基本配置流程

以下是在活字格设计器中添加一个 MCP 服务器的基本步骤。

  1. 打开应用程序设置

    在设计器顶部菜单栏，点击“文件”，然后选择“应用程序设置”。

  2. 添加 MCP 服务器配置

    在应用设置对话框中，找到“MCP 配置”配置项，点击“添加”按钮。

  3. 填写配置信息并测试

    在弹出的对话框中，根据你要连接的 MCP 服务器类型，填写相应信息。

填写完毕后，点击“测试”按钮。如果连接成功，系统会列出该服务器提供的可用工具列表。

  • 对于 StreamableHTTP/SSE 模式：主要填写服务器的URL。

  • 对于 Stdio 模式：主要填写程序的命令路径和参数。

  1. 保存配置

    测试通过后，点击“确定”保存该 MCP 服务器配置。

image

三、在应用中使用 MCP 工具

配置完成后，你可以在以下位置使用这些 MCP 工具：

1. 在 AI 对话单元格中使用

  • 在页面上放置一个“AI 对话单元格”。

  • 在右侧的属性设置中，找到“MCP 工具”列，下拉选择你刚才配置好的 MCP 服务器。

image

  • 运行时，你可以直接通过自然语言向 AI 下达指令，AI 会自动判断并调用合适的工具。例如：“几点了”。

image

  • 你可以点击结果旁的切换按钮，查看工具调用的详细信息（如参数、返回值等）。

image

2. 在 AI 助手命令中使用

  • 在客户端命令或服务端命令中，可以添加“AI 助手”命令节点。

  • 在该节点的属性设置中，同样可以勾选并配置要使用的 MCP 工具。

  • 命令执行后，你可以获取 MCP 工具的返回值，用于后续的业务逻辑。

四、高级配置选项

根据不同的认证和使用场景，你可能需要进行一些高级配置。

1. 自定义请求头 (Custom Headers)

当连接的 MCP 服务器需要 API 密钥（API Key）等认证信息时，你可以通过“Headers”进行配置。

配置方法：在 MCP 服务器配置中，添加一个键值对，例如：

  • 键（Key）：Authorization

  • 值（Value）：Bearer your-api-key

2. OAuth 2.0 认证

对于支持 OAuth 2.0 认证的 MCP 服务器，平台提供了简化的配置方式。

  • 配置方法：在 MCP 服务器配置中，填写clientId、clientSecret、tokenUrl和scope等字段。

  • 工作原理：配置后，活字格会在与服务器通信前，自动使用这些信息获取访问令牌（Access Token），并将其添加到请求头中。令牌过期后会自动刷新。

  • 注意：不建议同时配置 OAuth 和手动的Authorization请求头。

3. 使用环境变量 (Environment Variables)

为了避免在配置中硬编码路径或密钥，你可以使用环境变量。

  • 使用方法：在支持的字段中，使用 %变量名% 的格式引用环境变量。例如，%MY\_API\_KEY%。

  • 支持字段：command, url, args, env的值, headers的值, 以及oauth中的所有字段。

  • 注意：添加或修改了新的环境变量后，需要重启活字格设计器或服务器才能生效。

五、安全与交互功能

1. 执行前确认 (Confirm Before Execute)

为防止 AI 自动执行高风险操作（如删除数据、发送邮件），建议开启此功能。

  • 开启方法：在使用 MCP 工具的组件（如 AI 对话单元格）中，勾选“执行前确认”选项。

  • 效果：当 AI 决定调用该工具时，会先弹出一个确认框，由用户手动确认后才会执行。

image

2. 执行前后命令

在 AI 对话单元格中，提供了MCP执行前命令和MCP执行后命令两个事件。你可以在这两个事件中编写命令，实现自定义逻辑，例如记录日志或根据结果进行判断。

六、管理与维护

1. 在管理后台中管理

应用发布后，管理员可以在管理后台的“MCP 服务器”页面中，编辑现有 MCP 配置，或启用/禁用某个 MCP 服务。

image

2. 导入与导出配置

在设计器的应用设置中，你可以将配置好的 MCP 服务器列表导出为 JSON 文件，方便在不同项目间迁移或备份。也可以将此 JSON 文件用于其他支持 MCP 协议的客户端（如 VsCode / Cursor）。

七、注意事项与限制

  • 功能支持：当前版本主要支持 MCP 协议中的“工具（Tool）”部分，暂不支持提示词（Prompts）、资源（Resources）等其他部分。

  • 返回类型：当前版本主要处理返回类型为文本（Text）的 MCP 工具。

  • 错误处理：当 MCP 工具调用失败时，系统不会中断流程，而是会将错误信息作为上下文返回给 AI，AI 可能会尝试理解错误并进行修正，或向用户解释问题。