服务端命令作为MCP服务器

将活字格应用配置为 MCP 服务器

本文档旨在说明如何将你的活字格应用配置为一个 MCP 服务器。通过这种方式，你可以将应用服务端的业务逻辑（即服务端命令）封装为标准的 AI 工具，供外部的 AI 应用（MCP 客户端）调用。

一、核心概念

当你的活字格应用作为 MCP 服务器时，它扮演的是“工具提供方”的角色。这意味着，你在应用中创建的服务端命令，例如“查询订单状态”、“创建一条新的请假记录”等，都可以变成 AI 能够理解和调用的“工具”。

这在企业拥有多个业务系统时尤其有用，可以创建一个统一的 AI 入口，根据用户问题，智能地调用不同活字格应用提供的服务。

二、配置步骤

将服务端命令发布为 MCP 工具的过程非常直接。

1. 启用 MCP 服务器功能

在设计器顶部菜单栏，点击“文件”，然后选择“应用程序设置”。
在设置页面中，勾选“启用服务端命令作为 MCP 服务器”选项。

2. 选择要发布的服务端命令

点击“选择作为 MCP 服务器的服务端命令”链接，会弹出一个对话框。
在此对话框中，勾选你希望发布为 MCP 工具的服务端命令。
注意：只有公开的、HTTP 方法为 POST 或 GET 的服务端命令才能被选择。
选择完成后，点击“确定”。你可以在列表中看到已选中的命令。

3. （可选）在服务端命令中单独设置

你也可以在编辑单个服务端命令时，于其“常规”设置标签页中，独立勾选或取消“启用 MCP”的选项。

三、获取连接配置信息

当你将服务端命令发布为 MCP 工具后，其他 AI 应用（客户端）需要知道如何连接到你的服务。活字格为此提供了便捷的配置信息获取方式。

1. 在设计器中获取

在“应用设置”的“MCP 服务器”配置区域，点击“查看 MCP 服务器配置”按钮。
系统会提供用于“开发环境（本地调试）”和“生产环境（发布后）”的两种 JSON 配置示例。

2. 在管理后台获取

应用发布后，在管理后台的“服务端命令”页面，点击“查看 MCP 服务器配置”按钮。
弹出的对话框包含两个标签页：
- 配置：显示完整的 JSON 配置信息，其中已自动填充了当前应用的实际地址。你可以直接复制此配置，用于配置 MCP 客户端。
- MCP 工具列表：列出了当前应用发布的所有 MCP 工具及其描述，方便客户端的开发者了解你的应用提供了哪些能力。

四、认证方式说明

为保证安全，发布后的应用需要通过 OAuth 2.0 进行认证。本地调试运行时则无需认证。

以下是客户端连接你的 MCP 服务时可以使用的两种认证配置方式。

方法一：OAuth 2.0 自动认证 (推荐)

这是标准且推荐的方式，客户端可以自动获取和刷新访问令牌。

准备工作：在活字格管理后台的“安全设置”->“第三方授权”中，创建一个客户端，并为其分配访问服务端命令的权限（如 FGC\_AllAppsServerCommands）。你将获得一个客户端ID (clientId)和一个客户端密钥 (clientSecret)。
客户端配置：在调用端（MCP 客户端）的应用中，按以下格式配置。将url, clientId, clientSecret, 和 tokenUrl 替换为你的实际信息。

{
    "url": "http(s)://<应用发布地址>/api/mcp",
    "oauth": {
        "clientId": "在此填入你的客户端ID",
        "clientSecret": "在此填入你的客户端密钥",
        "tokenUrl": "http(s)://<管理后台地址>/UserService/connect/token"
    }
}

方法二：手动配置访问令牌

此方法适用于测试或某些不支持 OAuth 自动认证的客户端。

准备工作：同方法一，你需要先创建一个第三方授权客户端。然后，通过 API 调用工具（如 Postman）向tokenUrl地址请求一个访问令牌（Access Token）。
客户端配置：将获取到的令牌配置在请求头（Headers）中。

{
    "url": "http(s)://<应用发布地址>/api/mcp",
    "headers": {
        "Authorization": "Bearer 在此填入你获取的访问令牌"
    }
}

注意：此访问令牌有有效期，过期后需要手动重新获取并更新配置。

五、重要提示

命令的名称和描述：AI 模型依赖工具的名称和描述来判断何时调用它。因此，请为你的服务端命令编写清晰、准确的名称和描述，以便 AI 能正确理解其功能。
服务地址：你的活字格应用作为 MCP 服务器的服务地址（Endpoint）是固定的，格式为 http(s)://<应用发布地址>/api/mcp。