可嵌入 MCP

让您的嵌入用户一键将其自动化连接到 AI

功能说明

每个 Activepieces 项目都可以充当 MCP 服务器 —— AI 可以连接以运行该项目工作流的地方。

当您嵌入 Activepieces 时，您的用户通过您的应用登录，而不是 Activepieces。因此他们无法使用常规的”连接您的 AI”界面（这需要他们登录 Activepieces，但他们无法登录）。

可嵌入 MCP 解决了这个问题。您的用户在您的应用内点击一次授权按钮，您的后端就会获得一个令牌，用于通过 AI 运行该用户的自动化。

各方的职责：

  • 您的后端 —— 执行连接步骤并保存令牌。
  • 您的用户 —— 只需在您的应用内的弹出窗口中点击授权。
  • Activepieces —— 检查一切并为该用户的项目返回令牌。
这是标准的 OAuth。唯一特定于 Activepieces 的部分是一个 SDK 调用（`authorizeMcp`），它在您的应用内显示授权弹出窗口。

开始之前

嵌入功能应已经正常工作：

  1. 您已创建了签名密钥。
  2. 您的后端签署了用户令牌（JWT）。
  3. 您的前端已调用 activepieces.configure({ jwtToken, instanceUrl, … })。

下文中的 INSTANCE_URL 是您的 Activepieces 地址（例如 https://app.your-company.com）。

整体流程（6 步）

  1. 注册您的应用一次 → 获得一个 client_id。
  2. 生成两个随机码（一个”验证码”和一个”挑战码”）。
  3. 请求 Activepieces 启动连接 → 获得一个 authRequestId。
  4. 在您的应用中显示授权弹出窗口 → 用户点击授权 → 获得一个 code。
  5. 将 code 交换为令牌。
  6. 使用令牌运行用户的工作流。

步骤

这告诉 Activepieces 您的应用是谁。保存 `client_id` —— 它对所有用户都是相同的。 
```bash theme={null}
curl -X POST "$INSTANCE_URL/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App AI Assistant",
    "redirect_uris": ["https://app.your-company.com/mcp/callback"]
  }'
```

您会得到一个 `client_id`。

<Tip>
  `client_name` 是用户在弹出窗口中看到的名称（"**My App AI Assistant** 想要连接"）。如果省略，则显示为"未知应用"。
</Tip>
 生成一个随机的 `codeVerifier`，然后将其转换为 `codeChallenge`。保存验证码以备第 5 步使用。 
```ts theme={null}
import crypto from 'crypto';

const base64url = (b: Buffer) =>
  b.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');

const codeVerifier = base64url(crypto.randomBytes(45));
const codeChallenge = base64url(crypto.createHash('sha256').update(codeVerifier).digest());
```
 调用 `/authorize`。它不返回数据 —— 而是**重定向**。不要跟随重定向；只需从重定向地址中读取 `authRequestId`。 
```ts theme={null}
const params = new URLSearchParams({
  client_id: CLIENT_ID,
  redirect_uri: 'https://app.your-company.com/mcp/callback',
  response_type: 'code',
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
});

const res = await fetch(`${INSTANCE_URL}/authorize?${params}`, { redirect: 'manual' });
const location = res.headers.get('location'); // .../mcp-authorize?authRequestId=eyJ...
const authRequestId = new URL(location).searchParams.get('authRequestId');
```

<Warning>`authRequestId` 仅有效 10 分钟。请在显示弹出窗口前及时获取。</Warning>
 将 `authRequestId` 发送到您的前端并传递给 SDK。您的应用内会显示一个弹出窗口，用户点击授权。 
```ts theme={null}
const result = await activepieces.authorizeMcp({ authRequestId });

if (result.denied) {
  // 用户点击了拒绝
} else {
  // result.redirectUrl 类似于：.../mcp/callback?code=THE_CODE
  const code = new URL(result.redirectUrl).searchParams.get('code');
  // 将 `code` 发送到您的后端进行第 5 步
}
```
 在您的后端，将 `code`（加上第 2 步中的 `codeVerifier`）交换为令牌。 
```ts theme={null}
const res = await fetch(`${INSTANCE_URL}/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code,
    code_verifier: codeVerifier,
    redirect_uri: 'https://app.your-company.com/mcp/callback',
    client_id: CLIENT_ID,
  }),
});
const { access_token, refresh_token } = await res.json();
```

为此用户保存 `refresh_token`。`access_token` 有效期为 15 分钟；`refresh_token` 可获取新令牌，且可随时撤销。
 将您的 AI 指向 `INSTANCE_URL/mcp` 并带上令牌。它仅对该用户的项目有效。快速验证： 
```bash theme={null}
curl -X POST "$INSTANCE_URL/mcp" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

您将看到用户的工具和工作流返回。

获取新令牌 / 断开连接

当 15 分钟令牌过期时获取新令牌：

curl -X POST "$INSTANCE_URL/token" -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","refresh_token":"<REFRESH_TOKEN>","client_id":"<CLIENT_ID>"}'

断开连接（关闭 AI 访问）：

curl -X POST "$INSTANCE_URL/revoke" -H "Content-Type: application/json" \
  -d '{"token":"<REFRESH_TOKEN>","client_id":"<CLIENT_ID>"}'

可选：让用户管理其 MCP

添加一个按钮，让用户可以在您的应用内查看连接状态并开启或关闭工具：

await activepieces.mcpSettings();

须知事项

  • 在所有地方使用相同的 redirect_uri（注册、/authorize、/token）。如果不一致，将被拒绝。
  • authRequestId 有效期为 10 分钟 —— 在显示弹出窗口前生成它。
  • 令牌仅针对该用户的一个项目 —— 这样用户之间相互隔离。
  • Cursor 和 Claude Desktop 是不同的。 这些是用户自行安装和连接的工具，因此不使用此弹出窗口。可嵌入 MCP 适用于您的应用为用户运行的 AI。