如何逐步将 Activepieces 与 MCP 连接起来

将 Activepieces 与 MCP 连接后，您可以使用人工智能助手来…… 使用自然语言创建、审查和测试自动化程序。您可以让向导检查可用的集成、设置草稿并在发布前检测错误，而无需在可视化编辑器中手动构建每个步骤。

Activepieces 集成了自己的服务器，该服务器与以下平台兼容： 模型上下文协议该服务器作为自动化平台与 Claude Desktop、Claude.ai、Cursor 或 Windsurf 等客户端之间的标准化接口。

当前的集成远不止于公开几个操作。向导可以查询流程结构、搜索操作和触发器、管理表、分析失败的执行，而且，如果您授予它相应的权限， 修改或发布完整的自动化流程.

Activepieces MCP 服务器允许您执行哪些操作？

Activepieces MCP 服务器允许兼容的向导在平台内处理项目。它的主要功能并非取代自动化引擎，而是为模型提供一套受控的工具集。 通过对话检查和管理流程.

例如，您可以让它执行以下操作：

• 列出现有流程并检查哪些流程已启用。
• 阅读自动化流程的结构和配置。
• 针对特定任务找到合适的行动方案。
• 创建包含触发器和操作的完整流程。
• 向现有流程添加条件、循环或分支。
• 发布前请验证配置。
• 尝试每个步骤并检查结果。
• 检查执行失败的情况，并解释遇到的错误。
• 创建和修改 Activepieces 表或记录。

您还可以发现属于不同公司的股份。 件 平台的一部分。A Piece 是将 Gmail、Slack、Google Sheets 或 HubSpot 等服务可用的触发器和操作整合在一起的集成。

这不应与以下情况混淆： Activepieces 的原生代理平台内创建的代理是自动化流程的一部分，它使用模型在执行过程中做出决策。而MCP服务器则允许外部助手构建、检查或管理项目。

将 Activepieces 与 MCP 连接所需的内容

开始之前，请确保您已准备好以下物品：

• Activepieces Cloud 帐户或更新后的自管理安装。
• 您拥有足够权限的项目。
• 一款与远程MCP服务器兼容的客户端。
• 如果 Activepieces 托管在您的服务器上，请提供带有 HTTPS 的公共地址。
• 项目内已配置必要的连接。

您无需安装 Node.js 或运行单独的 MCP 服务器。Activepieces 已包含必要的端点，并提供类似如下的地址：

https://tu-instancia.example.com/mcp

如果您使用 Slack、Google Drive 或 CRM 等应用程序，请先通过 Activepieces 界面配置它们的连接。向导可以选择现有连接，但是 您将不会收到您的密码、API密钥或OAuth令牌。.

如何激活 Activepieces MCP 服务器

服务器已在项目设置中激活：

1. 登录Activepieces。
2. 打开您想要连接的项目。
3. 进入 设置.
4. 选择 MCP 服务器.
5. 使用相应的开关激活服务器。
6. 查看允许使用的工具类别。
7. 复制显示的地址 服务器 URL.

授权是按项目进行的。这样，助理就可以连接到测试环境，而无需授予他们访问生产环境中工作流程的权限。

首次连接时，建议仅启用查询工具。待验证客户端运行正常后，再启用创建、测试或发布功能。

如何连接 Claude Desktop、Cursor 或 Windsurf

支持远程 MCP 服务器的客户可以直接使用 Activepieces 提供的 URL。一般配置结构如下：

{
  "mcpServers": {
    "activepieces": {
      "url": "https://tu-instancia.example.com/mcp"
    }
  }
}

文件或设置的位置取决于客户端：

顾客	配置位置
光标	.cursor/mcp.json 为了项目或 ~/.cursor/mcp.json 全球
Windows 上的 Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
macOS 上的 Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
风帆冲浪	编辑器首选项中的 MCP 设置
Claude.ai	组织设置 > 连接器 > 添加 > 自定义连接器

保存设置后，如有必要，请重启客户端。首次连接时，将打开一个浏览器窗口完成设置。 使用 Activepieces 进行 OAuth 授权.

登录后，选择正确的项目，并授予所需的访问权限。客户端将存储一个授权令牌；无需手动将 API 密钥复制到配置文件中。

较旧的指南可能会显示类似于以下的命令： npx mcp-remote 以及以……结尾的地址 /sse该配置对应于之前的实现。在当前兼容的客户端上，您必须使用…… URL 以……结尾 /mcp.

助理可以使用哪些工具？

Activepieces 将其 MCP 工具分为几个类别。这些工具包括： 发现 它们为只读类型，且始终可用。每个项目中都可以启用或禁用能够修改数据的类别。

类别	它能让你做什么
发现	查看流程、连接、部件、表格、执行和验证错误。
流量管理	创建、复制、重命名、发布、启用、禁用或删除流程。
流程构建	添加、更新和删除触发器或操作。
路由器和分支	创建和修改条件分支。
注释	在画布上添加和管理注释。
表格	创建表、字段和记录，以及修改或删除它们。
测试与运行	测试流程，执行操作，查看结果，并重试失败的执行。

某些操作会产生重大后果。删除工作流的工具也会删除其所有版本。 它不允许撤销该操作。同样，执行操作可以使用真实连接发送电子邮件、修改记录或发布内容。

因此，不建议自动启用所有类别。仅授予助手执行当前任务所需的权限即可。

如何使用自然语言创建 Activepieces 工作流程

连接建立后，您就可以描述所需的自动化功能。指令越精确，模型需要做出的模糊决策就越少。

例如：

创建一个禁用草稿，该草稿在周一至周五上午 9:00 运行，查询 ActivePieces 表中的待处理记录，并将摘要发送到 Slack。仅使用现有连接。验证并测试该流程，但不要发布。

通常流程应按以下顺序进行：

1. 查看项目： 向导会检查可用的流、表和连接。
2. 找到所需的工具： 找出触发因素以及最合适的应对措施。
3. 查看其属性： 获取所需字段和允许的选项。
4. 创建草稿： 按正确的顺序构建触发器和步骤。
5. 验证结构： 检查引用、空分支和不完整字段。
6. 参加测试： 使用受控数据执行流程或某些步骤。
7. 查看结果： 它显示了输入、输出、时间和可能出现的错误。
8. 发布并启用： 请在确认后再执行这些操作。

ActivePieces 可以一次性创建整个流程，但这并不意味着您应该在未审核的情况下发布它。打开向导返回的链接，并直观地检查所使用的连接、表达式和字段。

如果缺少连接，向导会告诉您在哪里配置，但您仍然需要通过 Activepieces 界面完成授权过程。这种设计有助于…… 在不泄露凭证的情况下，将人工智能代理连接到内部系统。.

操作和触发搜索的工作原理

该函数 工具搜索 它允许助手描述任务，例如“向 Slack 频道发送消息”，并从目录中接收最相关的操作。

发现流程分为三个阶段：

1. 发现： 使用自然描述搜索操作或触发器。
2. 检查： 它获取所选选项的完整模式和字段。
3. 执行或构建： 可以一次性使用该操作，也可以将其整合到持续流程中。

Activepieces Cloud 已启用工具搜索功能。在自行管理的安装中，您必须使用以下变量激活它：

AP_TOOL_SEARCH_ENABLED=true

该更改是动态读取的，无需重启实例。为了获得语义结果，Activepieces 还需要嵌入模型和带有相应扩展的 PostgreSQL 数据库。 pgvector.

您可以通过以下方式提供用于嵌入的密钥：

AP_OPENAI_API_KEY=tu_clave

您还可以通过平台管理界面将 OpenAI 配置为提供商。如果没有可用的嵌入模型或语义索引失败，工具搜索将继续使用 OpenAI 运行。 关键词匹配.

如何保护 Activepieces MCP 访问权限

服务器使用 OAuth 认证，将操作限制在已授权的项目范围内，并且不会向客户端返回存储的密钥或令牌。然而，保护密钥并不能消除所有风险：拥有执行工具的向导仍然可以…… 间接使用这些凭证 采取实际行动。

在使用 MCP 进行大规模自动化之前，请先采取以下措施：

• 创建一个单独的项目用于初始测试。
• 仅激活必要的工具类别。
• 使用权限最小的应用账号。
• 除非必要，否则不要允许发布、删除或启用流程。
• 发送消息或修改外部数据前，请先请求确认。
• 发布草稿前请手动检查结构。
• 每次重大变更后，请查看执行情况和日志。
• 如果设备或客户端不再使用，则撤销 OAuth 授权。

对于财务流程、CRM变更、对外沟通或信息删除，建议 在人工智能工作流程中加入人工审核该模型可以准备操作，但最后一步必须由人授权。

自托管允许您将 Activepieces 保留在您自己的基础架构中，但是 并不自动保证符合监管要求。最终的安全性还取决于代理、数据库、权限、备份和组织策略。

如何在反向代理后配置 MCP

在自托管安装中，Activepieces 公共地址必须可从 MCP 客户端访问，并且具有有效的 HTTPS 连接。如果实例发布在域的根目录中，则典型的端点为：

https://automatizacion.example.com/mcp

当 Activepieces 位于子路由下时，您必须将其包含在内。 AP_FRONTEND_URL:

AP_FRONTEND_URL=https://automatizacion.example.com/activepieces

在这种情况下，MCP 服务器可通过以下方式访问：

https://automatizacion.example.com/activepieces/mcp

代理必须转发 Activepieces 流量和 OAuth 授权期间使用的端点。某些客户端会查找路由。 /.well-known/oauth-* 直接在域名根目录下。如果客户端忽略了发现标头，则需要创建一条额外的规则来转发这些路由。

不要直接通过 HTTP 暴露测试容器。请使用稳定的域名、TLS 和正确的配置。 AP_FRONTEND_URL因为内部地址和公共地址之间的差异可能会破坏 OAuth 重定向。

将 Activepieces 与 MCP 连接时常见的错误

客户端尝试使用 mcp-remote 或以 /sse 结尾的地址

您正在参考的是早期版本的指南。当前服务器是使用以 . 结尾的远程 URL 进行配置的。 /mcp删除旧命令并重新注册服务器。

MCP 服务器选项未启用

进入 设置 > MCP 服务器激活服务并再次复制地址。另外，请确认您正在处理的项目是否正确。

OAuth授权进入循环

请确认公网地址完全匹配。 AP_FRONTEND_URL如果您正在使用子路由，请检查代理规则和 OAuth 发现端点。

助手只能读取流程图。

发现工具为只读模式，请显式启用。 流量管理, 流程构建 或项目 MCP 配置中要求的其他类别。

股票搜索工具没有显示。

在自管理实例中，验证 AP_TOOL_SEARCH_ENABLED=true如果搜索有效但只找到字面匹配项，请检查嵌入提供商和可用性。 pgvector.

巫师找到了一个动作，但却无法执行。

集成可能需要一个尚不存在或出现错误的连接。请打开 Activepieces，通过界面配置连接，然后再次请求执行。

助理在做错误的项目。

要求程序显示可用项目，并明确设置正确的上下文。后续操作将仅限于该项目。

流程已创建，但未运行。

检查它是否仍为草稿、是否已发布以及其状态是否为…… 已启用还要检查触发器是否有有效样本，以及所有连接是否处于活动状态。

测试通过，但实际执行失败。

查看执行历史记录并打开每个步骤的结果。测试可能使用了与实际触发事件随后接收到的数据不同的样本数据。

助手准备的行动风险过高。

不要直接运行。减少允许的类别，修改提示信息以要求确认，并在任何不可逆操作之前增加人工审批环节。

将 ActivePieces 与 MCP 连接后，向导程序会变成一个用于构建和维护自动化流程的界面，但默认情况下并不授予无限制访问权限。服务器会将查询工具与写入功能分离，并将凭据保存在项目内部。

推荐的设置步骤包括激活 MCP 服务器、复制其 URL、通过 OAuth 授权客户端，并首先启用只读工具。之后，您可以逐步启用构建、测试和发布功能，并在使用真实数据或帐户之前审查每个工作流程。