MCP Server

把你的 AI 工具 — Claude Code、Cursor、Codex、Claude Desktop 等 — 连接到 Imbrace，它就能直接操作你的 Imbrace 数据：列出 CRM 看板、读取会话、查看工作流运行等。

你只需要两样东西：

• 一个 URL — Imbrace 网关在 /mcp 托管了一个 Model Context Protocol 服务器，无需安装或自行运行任何东西。
• 一个 API key — 作为 Bearer token 发送。代理只能看到你的组织和角色允许的内容，不会更多。

第 1 步 — 获取 API key

在 Imbrace Dashboard 生成外部 token（参见获取 API Key），形如 api_...。

第 2 步 — 连接你的工具

在下方选择你的工具并粘贴配置。示例使用 sandbox 网关 — 请替换为你所在环境的网关主机名。

Claude Code

一条命令：

claude mcp add --transport http imbrace "https://app-gateway.sandbox.imbrace.co/mcp" \
  --header "Authorization: Bearer api_xxx..."

Cursor

添加到项目中的 .cursor/mcp.json — 或 ~/.cursor/mcp.json 以全局启用：

{
  "mcpServers": {
    "imbrace": {
      "url": "https://app-gateway.sandbox.imbrace.co/mcp",
      "headers": { "Authorization": "Bearer api_xxx..." }
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml（支持 HTTP MCP 的新版 Codex）：

[mcp_servers.imbrace]
url = "https://app-gateway.sandbox.imbrace.co/mcp"
bearer_token = "api_xxx..."

旧版 Codex 不支持 HTTP 时，通过 mcp-remote 桥接：

[mcp_servers.imbrace]
command = "npx"
args = ["-y", "mcp-remote", "https://app-gateway.sandbox.imbrace.co/mcp", "--header", "Authorization: Bearer api_xxx..."]

Claude Desktop

Claude Desktop 只启动本地服务器，因此用 mcp-remote 桥接 URL。在 Settings → Developer → Edit Config 中，添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "imbrace": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://app-gateway.sandbox.imbrace.co/mcp",
        "--header", "Authorization: Bearer api_xxx..."
      ]
    }
  }
}

其他客户端

任何接受 URL 加请求头的 MCP 客户端都使用标准形式：

{
  "mcpServers": {
    "imbrace": {
      "url": "https://app-gateway.sandbox.imbrace.co/mcp",
      "headers": { "Authorization": "Bearer api_xxx..." }
    }
  }
}

如果客户端只支持本地（stdio）服务器，用以下方式桥接：

npx -y mcp-remote "https://app-gateway.sandbox.imbrace.co/mcp" \
  --header "Authorization: Bearer api_xxx..."

第 3 步 — 试一试

问你的代理，例如*“列出我的 Imbrace 看板”或”看看最新的会话”*。它会自动选用 listBoards、listConversations、listFlows 等工具。

默认只读

默认情况下代理只能看、不能改 — 只暴露读取工具。要开放更多权限，在所配置的 URL 上添加查询参数：

添加到 URL	效果
?allowWrite=1	代理还可以创建和修改数据
?allowDestructive=1	代理还可以删除数据（包含 write）
?services=dataBoard,workflow	收窄：仅这些服务
?tags=boards,records	收窄：仅这些主题

示例 — 仅数据看板，带写入权限：

https://app-gateway.sandbox.imbrace.co/mcp?services=dataBoard&allowWrite=1

服务：dataBoard、channel、platform、marketplace、workflow。代理调用未启用的工具会收到明确错误 — 不会静默失败。

工作原理

每次工具调用都会带着你的 token 经网关的正常 API 路由重放，因此组织范围、权限与 license 检查与你亲自调用 API 完全一致。工具即精选的 agent-tools 操作集，与 SDK 的 client.api 表面同源。端点是基于 HTTP POST 的无状态 JSON-RPC — 无需管理会话。

不用 MCP？统一 OpenAPI

使用 OpenAPI 工具规范而非 MCP 的平台（如 Open WebUI）可以指向 GET /agent-tools/openapi.json（同样的 Authorization 头）：所有服务的 agent-tools 合并为一份 spec，支持同样的 ?services= / ?tags= 过滤 — 一个工具服务器而不是五个。把基础 URL 与操作路径简单拼接的执行器（请求成 /agent-tools/<op-path>）也能兼容：网关会去掉前缀并带你的凭证重放请求。

本地替代方案 — CLI

想要本地 stdio 服务器（凭证来自 CLI profile，无需配置 URL）？CLI 内置同一套工具注册表：imbrace mcp。