Dureach

通过 MCP 连接 AI 客户端

通过可流式传输的 HTTP 将外部 MCP 客户端连接到 Dureach，完成 OAuth 同意，并安全调用 tools/list 与 tools/call。

Dureach 在 https://app.dureach.com/mcp 为外部 MCP 客户端提供读取与操作兼备的 MCP 服务器。客户端完成 OAuth 同意，调用 tools/list 以发现已授权工具，然后使用 dureach.* 工具名称和类型化参数调用 tools/call。

工具结果会传输到外部客户端，其提供商可能处理或保留这些数据。连接前，请审核提供商的数据处理、保留和访问条款。仅请求任务必需的字段；不要在共享对话、截图或日志中包含联系人详情和客户记录。

连接前需要准备什么？

  1. 已启用智能体平台能力的工作区。未启用时，准入将返回 plan_capability_required。
  2. 可完成浏览器同意授权的 OAuth 客户端。MCP 仅接受 OAuth Bearer 令牌；REST API 密钥在 /mcp 上会被拒绝。
  3. 以工作区成员身份在浏览器中完成授权。 将凭据保存在客户端受保护的凭据存储或服务器端密钥管理器中。不要将令牌粘贴到对话、共享文档、截图或工单中。
  4. 支持可流式传输的 HTTP 与 JSON 响应的 MCP 客户端（例如带 MCP 连接器的 Claude Desktop、Cursor，或基于 mcp SDK 构建的自定义 Python 客户端）。

MCP 的 OAuth 同意流程是怎样的？

  1. 注册或打开 OAuth 客户端，为该工作区启动授权流程。
  2. 仅选择客户端所需的范围（参见《MCP 审批、策略与配额》。报告类客户端可能仅需要 companies:read 和 trade:read；外联类客户端还需要 leads:create 或 emails:send 等授权。
  3. 以工作区成员身份在浏览器中完成授权。 将凭据保存在客户端受保护的凭据存储或服务器端密钥管理器中。不要将令牌粘贴到对话、共享文档、截图或工单中。
  4. 在每次 MCP HTTP 请求中以 Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN 发送令牌。不要将其放入 URL、截图、日志和工单。
  5. 若客户端须代表特定工作区操作，请发送 X-Workspace-ID 并填写令牌所属工作区 ID。不匹配的值将返回 workspace_context_required。

当客户端库需要发现值时，请查阅 /.well-known/oauth-protected-resource/mcp 处的元数据文档。

客户端使用什么端点和协议？

  • 使用准确的地址 https://app.dureach.com/mcp 和支持 streamable HTTP 的 MCP 客户端。
  • 为目标工作区完成 OAuth 授权；凭据应保存在客户端受保护的凭据存储或服务器端密钥管理器中。
  • 若主机或来源被拒绝，检查连接地址并联系支持人员。不要删除或伪造安全标头以绕过拒绝。
  • 保留响应中的 request_id 以便排查；不要在共享日志中包含令牌或结果行。

如何列出可用工具？

OAuth 授权后调用 tools/list。每个可用工具包含名称和参数结构。调用前请使用返回的结构验证请求。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

使用 tools/list 查看此连接可用的工具。可用范围取决于已授予的权限和工作区访问资格。先授予读取权限；若缺少访问权限，请工作区管理员审核，不要申请宽泛权限。

如何调用工具？

发送 tools/call 请求，填写完整的 dureach. 名称和参数对象。未知名称或缺少该前缀的名称返回 Unknown tool（INVALID_PARAMS）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "dureach.companies.search",
    "arguments": {"query": "industrial valves", "page": 1, "limit": 10}
  }
}

成功结果返回一个包含 JSON 的文本条目，以及一份已解析的 structuredContent 副本。应用层失败返回 isError: true，并附带 {"error": {"code": "...", "details": {...}}, "request_id": "..."}。请保存 request_id 以用于支持与重试处理。完整参数边界请参阅《MCP 工具参考》。

如何配置常见客户端？

Claude Desktop 或其他基于连接器的客户端

  1. 添加可流式传输的 HTTP 服务器，URL 为 https://app.dureach.com/mcp。
  2. 使用 Dureach OAuth 注册中的客户端 ID 配置 OAuth 身份验证，并填写 MCP 资源元数据 URL。
  3. 完成同意，然后确认连接器列出的工具以 dureach. 开头。
  4. 运行数据搜索前，请先调用 dureach.workspace.context 和 dureach.workspace.capabilities。

自定义 Python 客户端（官方 mcp SDK）

import os

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://app.dureach.com/mcp"
TOKEN = os.environ["DUREACH_OAUTH_ACCESS_TOKEN"]

async def main():
    async with streamable_http_client(
        MCP_URL, headers={"Authorization": f"Bearer {TOKEN}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool(
                "dureach.companies.search",
                {"query": "industrial valves", "page": 1, "limit": 10},
            )
            print("Search completed")

请将令牌和查询替换为实际值。切勿将令牌提交至源代码管理。

共享访问前应运行哪些检查？

  1. 调用 dureach.workspace.context，确认返回的工作区 ID 与范围符合预期工作区。
  2. 调用 dureach.workspace.capabilities，确认仅显示预期的操作。
  3. 运行一次有界读取（例如使用 limit: 5 调用 companies.search），确认分页字段。
  4. 对于写入路径，先使用 dry_run: true 运行；参见《MCP 审批、策略与配额》。
  5. 不再需要访问时，在 /oauth/revoke 撤销令牌，或在 Settings → Integrations 中撤销。

相关页面