接入指南 - Clawdot虾点·文档中心

快速开始

Skills 平台以 MCP（Model Context Protocol） 作为对外接入协议。Clawdot Gateway 通过 Streamable HTTP 暴露 24 个外卖 MCP 工具——授权、店铺、地址、下单、支付一条链路全覆盖。把网关配置成一个远程 MCP 服务器，你的 Agent 就能自动发现并调用这些工具。

MCP（推荐主线）

适合 Claude Desktop、Cursor 等支持 MCP 的客户端，以及任何能连接远程 MCP 的 Agent 框架。Streamable HTTP 接入，工具自动发现，零样板代码。

自建封装（Function Calling）

平台暂不支持远程 MCP？按同一套工具契约（工具名 + 参数）把这些工具注册成你框架里的函数工具，在函数实现里转发到 MCP。

本页是叙述式上手指南。无论哪种接入方式，背后都是同一套契约：24 个外卖 MCP 工具，工具名、参数与返回结构一致。完整字段表见 MCP 概览；端到端下单顺序见下单流程。

MCP 协议

MCP（Model Context Protocol）是 Anthropic 推出的标准协议，支持 Claude Desktop、Cursor 等客户端轻松接入 Skills 平台。Clawdot Gateway 通过 Streamable HTTP 暴露 MCP 接口。

步骤 1：获取 API Key

在 Clawdot 控制台创建你的 Agent：

登录控制台，进入 Agent 管理
点击 创建新 Agent，填写名称和描述
系统自动生成 API Key（clw_ 开头）
复制 API Key 到安全位置

API Key 仅在创建时显示一次。如果遗失，需要在控制台重新生成。详见认证机制。

步骤 2：配置 MCP 服务器

Gateway 的 MCP 公开端点是 https://eleme-gateway.hicaspian.com/mcp/v1（Streamable HTTP）。Agent 身份通过 Authorization: Bearer clw_... 请求头在连接层传递。在支持 Streamable HTTP 远程 MCP 的客户端中配置：

{
  "mcpServers": {
    "clawdot-eleme": {
      "type": "http",
      "url": "https://eleme-gateway.hicaspian.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer clw_your_api_key_here"
      }
    }
  }
}

配置说明：

参数	说明	示例
`url`	Gateway 的 MCP 公开端点（Streamable HTTP）	`https://eleme-gateway.hicaspian.com/mcp/v1`
`Authorization`	Agent 身份，`Bearer` + 你的 API Key	`Bearer clw_abc123def456...`

不要将 API Key 提交到版本控制系统。优先用环境变量管理敏感信息，例如把 Authorization 头的值从环境变量注入。注意公开端点路径是 /mcp/v1：网关把 MCP 应用挂载在 /mcp 下，FastMCP 内部路由版本化为 /v1。端点细节见 MCP 概览。

API Key 只标识 Agent 身份；要替某位用户下单，还需要该用户的授权（consent grant）。当用户首次使用你的 Agent 时，走一次绑定流程拿到 consent_grant_id：

# 步骤 3a：发起绑定（SMS 验证码模式）
request_user_bind(
    phone="13800138000",
    auth_type="sms",
)

# 返回示例
{
  "bind_id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_in": 300   # 验证码有效期（秒）
}

# 步骤 3b：用户输入验证码后，确认绑定并拿到 consent_grant_id
verify_user_bind(
    bind_id="550e8400-e29b-41d4-a716-446655440000",
    code="123456",
    auth_type="sms",
)

# 返回示例
{
  "consent_grant_id": "cg_550e8400e29b41d4a716",   # 之后每次调用都要带上
  "scopes": ["taobao_flash.delivery"],             # 授权能力范围
  "expires_at": "2026-09-15T10:00:00Z"             # 过期时间（ISO 8601）
}

也支持 H5 授权模式（auth_type="h5"，request_user_bind 返回授权链接）。完整字段与回调说明见发起绑定与确认绑定。

步骤 4：调用 Gateway 技能

通过 MCP 协议，你的 Agent 可以自动发现和调用所有 Gateway 工具。MCP 客户端会在工具栏中展示所有可用工具。调用时把上一步拿到的 consent_grant_id 作为每个工具的参数传入（不是请求头）。 示例对话：

用户：我想在附近点一份外卖 Claude：我可以帮你搜索附近的餐厅。首先，请告诉我你的位置或地址。用户：中关村大街1号 Claude：【调用 Gateway 工具 search_shops（带 consent_grant_id）】正在搜索中关村大街附近的餐厅… … 返回推荐列表

下单是一条有状态的链路：算价 → 选地址 → 预览 → 下单 → 签约支付，跨步 ID 由网关签发、原样回传。完整工具列表与下单链路见 MCP 概览与下单流程。

自建封装（Function Calling）

如果你的平台暂时不支持远程 MCP，可以按同一套工具契约把这些工具注册成你框架里的函数工具（如 OpenAI Function Calling、LangChain、LlamaIndex），在函数实现里把调用转发到 MCP。工具名、参数、返回结构与 MCP 完全一致——你封装的只是”调用通道”，业务语义不变。

步骤 1：获取 API Key

同上（在控制台创建 Agent）。

步骤 2：用户授权

同上，走一次绑定流程拿到 consent_grant_id。

步骤 3：按工具契约注册函数工具

把 Gateway 工具注册为你框架的函数工具。工具名与参数严格对齐工具契约——这样模型产出的工具调用可以直接喂给网关，无需翻译：

from openai import OpenAI

client = OpenAI(api_key="sk-...")

# 按 Gateway 工具契约定义函数工具（工具名/参数与 MCP 一致）
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_shops",
            "description": "搜索 / 浏览本地商店（外卖、商超、便利店等）",
            "parameters": {
                "type": "object",
                "properties": {
                    "keyword": {
                        "type": "string",
                        "description": "可选：店名、品类或商品名（如 生椰拿铁）。省略则浏览附近店铺"
                    },
                    "address_id": {
                        "type": "string",
                        "description": "已保存地址 ID；省略时需传 lat/lng"
                    },
                    "lat": {"type": "number", "description": "纬度（GCJ-02）"},
                    "lng": {"type": "number", "description": "经度（GCJ-02）"}
                },
                "required": []
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_shop_menu",
            "description": "获取店铺菜单，返回可下单的 item_id / sku_id",
            "parameters": {
                "type": "object",
                "properties": {
                    "shop_id": {"type": "string", "description": "来自 search_shops"},
                    "cart_id": {"type": "string", "description": "来自 search_shops，原样回传"},
                    "keyword": {"type": "string", "description": "可选：只返回命中商品"}
                },
                "required": ["shop_id", "cart_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "preview_order",
            "description": "预览订单，返回下单用的 preview_id + confirmation_token",
            "parameters": {
                "type": "object",
                "properties": {
                    "shop_id": {"type": "string"},
                    "cart_id": {"type": "string"},
                    "address_id": {"type": "string"},
                    "items": {
                        "type": "array",
                        "description": "选好的商品列表（list，不是 JSON 字符串）",
                        "items": {
                            "type": "object",
                            "properties": {
                                "item_id": {"type": "string"},
                                "sku_id": {"type": "string"},
                                "quantity": {"type": "integer"}
                            }
                        }
                    }
                },
                "required": ["shop_id", "cart_id", "address_id", "items"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "create_order",
            "description": "用预览产出的 preview_id + confirmation_token 创建订单",
            "parameters": {
                "type": "object",
                "properties": {
                    "preview_id": {"type": "string", "description": "来自同一次 preview_order"},
                    "confirmation_token": {"type": "string", "description": "来自同一次 preview_order"}
                },
                "required": ["preview_id", "confirmation_token"]
            }
        }
    }
]

# 调用 ChatCompletion API
messages = [
    {"role": "user", "content": "我想在中关村点一份外卖"}
]

response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

# 处理模型产出的工具调用
for tool_call in response.tool_calls:
    if tool_call.function.name == "search_shops":
        # 转发到 Gateway MCP（见下一步）
        # ...

步骤 4：函数实现 —— 转发到 MCP

每个函数把模型产出的参数（补上当前用户的 consent_grant_id）通过你的 MCP 客户端转发到对应工具。Agent 身份在 MCP 连接层用 API Key 标识，consent_grant_id 作为工具参数传入：

import json

def call_gateway_tool(mcp_client, tool_name, tool_args, consent_grant_id):
    """通过已连接的 Gateway MCP 客户端调用一个工具。
    mcp_client 已用 Authorization: Bearer clw_... 连接到
    https://eleme-gateway.hicaspian.com/mcp/v1（Streamable HTTP）。"""
    # 业务工具都要带 consent_grant_id 参数；
    # 绑定类工具 request_user_bind / verify_user_bind 除外（它们是拿授权的入口）。
    args = {**tool_args}
    if tool_name not in ("request_user_bind", "verify_user_bind"):
        args["consent_grant_id"] = consent_grant_id
    return mcp_client.call_tool(tool_name, args)

def execute_tool(mcp_client, tool_name, tool_args, consent_grant_id):
    """执行模型产出的一次工具调用，原样转发到 MCP。"""
    if tool_name in ("search_shops", "get_shop_menu", "preview_order", "create_order"):
        result = call_gateway_tool(mcp_client, tool_name, tool_args, consent_grant_id)
        return json.dumps(result, ensure_ascii=False)

工具名、参数、返回结构与 MCP 完全一致——封装层只负责”把模型产出的工具调用转发到网关”。完整字段见购物车算价 · 预览订单 · 创建订单。

对比选择

维度	MCP（推荐主线）	自建封装（Function Calling）
适用平台	Claude Desktop、Cursor，及支持远程 MCP 的框架	暂不支持远程 MCP 的 OpenAI 兼容框架
配置复杂度	极低（JSON 配置）	中等（需自己定义 Schema 并转发到 MCP）
工具发现	自动	手动（按契约逐个声明）
学习成本	低	中
生产就绪	是	是

推荐选择：

MCP：首选主线。客户端/框架支持远程 MCP 时，配置一个服务器即可，工具自动发现、零样板。
自建封装（Function Calling）：仅当平台暂不支持远程 MCP。按同一套工具契约声明函数工具，在实现里转发到 MCP；后续平台支持 MCP 后可平滑切换。

​快速开始

MCP（推荐主线）

自建封装（Function Calling）

​MCP 协议

​步骤 1：获取 API Key

​步骤 2：配置 MCP 服务器

​步骤 3：用户授权（consent grant）

​步骤 4：调用 Gateway 技能

​自建封装（Function Calling）

​步骤 1：获取 API Key

​步骤 2：用户授权

​步骤 3：按工具契约注册函数工具

​步骤 4：函数实现 —— 转发到 MCP

​对比选择

​故障排查

快速开始

MCP 协议

步骤 1：获取 API Key

步骤 2：配置 MCP 服务器

步骤 3：用户授权（consent grant）

步骤 4：调用 Gateway 技能

自建封装（Function Calling）

步骤 1：获取 API Key

步骤 2：用户授权

步骤 3：按工具契约注册函数工具

步骤 4：函数实现 —— 转发到 MCP

对比选择

故障排查