Integration Guide

Quick Start

The Skills Platform uses MCP (Model Context Protocol) as its integration protocol. Clawdot Gateway exposes 24 delivery MCP tools over Streamable HTTP — covering the whole chain: authorization, shops, addresses, ordering, and payment. Configure the gateway as a remote MCP server and your Agent can auto-discover and call these tools.

MCP (recommended)

For clients that support MCP like Claude Desktop and Cursor, and any Agent framework that can connect to a remote MCP server. Streamable HTTP, automatic tool discovery, zero boilerplate.

Self-built wrapper (Function Calling)

Platform doesn’t support remote MCP yet? Register the tools as function tools in your framework against the same tool contract (tool name + parameters), and forward each call to MCP in the function implementation.

This is a narrative getting-started guide. Whichever way you integrate, it sits on one contract: 24 delivery MCP tools with the same tool names, parameters, and response shapes. For full field tables see MCP Overview; for the end-to-end ordering sequence see Order Flow.

MCP Protocol

MCP (Model Context Protocol) is the standard protocol released by Anthropic, enabling client applications like Claude Desktop and Cursor to easily integrate with the Skills Platform. Clawdot Gateway exposes its MCP interface over Streamable HTTP.

Step 1: Get API Key

Create your Agent in the Clawdot Console:

Sign in to the console and open Agent Management
Click Create New Agent, enter a name and description
The system auto-generates an API Key (starting with clw_)
Copy the API Key to a safe location

The API Key is only displayed once at creation. If lost, regenerate it in the console. See Authentication.

Step 2: Configure MCP Server

The Gateway’s public MCP endpoint is https://eleme-gateway.hicaspian.com/mcp/v1 (Streamable HTTP). Agent identity is passed at the connection layer via the Authorization: Bearer clw_... header. Configure it in any client that supports remote Streamable HTTP MCP:

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

Configuration Parameters:

Parameter	Description	Example
`url`	Public MCP endpoint (Streamable HTTP)	`https://eleme-gateway.hicaspian.com/mcp/v1`
`Authorization`	Agent identity, `Bearer` + your API Key	`Bearer clw_abc123def456...`

Do not commit the API Key to version control. Prefer environment variables for sensitive data, e.g. inject the Authorization header value from an env var.Note the public endpoint path is /mcp/v1: the gateway mounts the MCP app under /mcp, and FastMCP’s internal route is versioned to /v1. For endpoint details see MCP Overview.

The API Key only identifies the Agent. To act on behalf of a user, you also need that user’s authorization (consent grant). The first time a user uses your Agent, run a binding flow once to obtain a consent_grant_id:

# Step 3a: Start binding (SMS code mode)
request_user_bind(
    phone="13800138000",
    auth_type="sms",
)

# Response example
{
  "bind_id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_in": 300   # code validity (seconds)
}

# Step 3b: After the user enters the code, confirm and obtain consent_grant_id
verify_user_bind(
    bind_id="550e8400-e29b-41d4-a716-446655440000",
    code="123456",
    auth_type="sms",
)

# Response example
{
  "consent_grant_id": "cg_550e8400e29b41d4a716",   # include on every later call
  "scopes": ["taobao_flash.delivery"],             # authorized capability scope
  "expires_at": "2026-09-15T10:00:00Z"             # expiry (ISO 8601)
}

An H5 authorization mode is also supported (auth_type="h5", request_user_bind returns an authorization link). For full fields and callback behavior see Start Binding and Confirm Binding.

Step 4: Call Gateway Skills

Through the MCP protocol, your Agent can auto-discover and call all Gateway tools. The MCP client displays all available tools in its toolbar. When calling, pass the consent_grant_id from the previous step as a parameter on each tool (not a header). Example conversation:

User: I want to order food nearby Claude: I can help you search for nearby restaurants. First, please tell me your location or address. User: No. 1 Zhongguancun Avenue Claude: [Calling Gateway tool search_shops (with consent_grant_id)] Searching for restaurants near Zhongguancun Avenue… … returns recommendation list

Ordering is a stateful chain: quote → select address → preview → create → sign and pay, with cross-step IDs minted by the gateway and passed through verbatim. For the full tool list and ordering chain see MCP Overview and Order Flow.

Self-built Wrapper (Function Calling)

If your platform does not yet support remote MCP, you can register the tools as function tools in your framework (OpenAI Function Calling, LangChain, LlamaIndex, etc.) against the same tool contract, and forward each call to MCP in the function implementation. The tool names, parameters, and response shapes are identical to MCP — all you wrap is the “call channel”; the business semantics are unchanged.

Step 1: Get API Key

Same as above (create an Agent in the Console).

Step 2: User Authorization

Same as above; run a binding flow once to obtain a consent_grant_id.

Step 3: Register Function Tools Against the Tool Contract

Register Gateway tools as your framework’s function tools. Tool names and parameters mirror the tool contract exactly — so the tool calls the model produces can be forwarded to the gateway without translation:

from openai import OpenAI

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

# Define function tools against the Gateway tool contract (names/params match MCP)
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_shops",
            "description": "Search / browse local shops (food delivery, supermarkets, convenience stores, etc.)",
            "parameters": {
                "type": "object",
                "properties": {
                    "keyword": {
                        "type": "string",
                        "description": "Optional: shop name, category, or item name (e.g. iced latte). Omit to browse nearby shops"
                    },
                    "address_id": {
                        "type": "string",
                        "description": "Saved address id; required when lat/lng omitted"
                    },
                    "lat": {"type": "number", "description": "Latitude (GCJ-02)"},
                    "lng": {"type": "number", "description": "Longitude (GCJ-02)"}
                },
                "required": []
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_shop_menu",
            "description": "Get a shop's menu, returning orderable item_id / sku_id",
            "parameters": {
                "type": "object",
                "properties": {
                    "shop_id": {"type": "string", "description": "From search_shops"},
                    "cart_id": {"type": "string", "description": "From search_shops, pass through verbatim"},
                    "keyword": {"type": "string", "description": "Optional: only return matched items"}
                },
                "required": ["shop_id", "cart_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "preview_order",
            "description": "Preview the order, returning preview_id + confirmation_token for ordering",
            "parameters": {
                "type": "object",
                "properties": {
                    "shop_id": {"type": "string"},
                    "cart_id": {"type": "string"},
                    "address_id": {"type": "string"},
                    "items": {
                        "type": "array",
                        "description": "Chosen items (a list, not a JSON string)",
                        "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": "Create the order with the preview_id + confirmation_token returned by the preview",
            "parameters": {
                "type": "object",
                "properties": {
                    "preview_id": {"type": "string", "description": "From the same preview_order"},
                    "confirmation_token": {"type": "string", "description": "From the same preview_order"}
                },
                "required": ["preview_id", "confirmation_token"]
            }
        }
    }
]

# Call ChatCompletion API
messages = [
    {"role": "user", "content": "I want to order food in Zhongguancun"}
]

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

# Handle the tool calls the model produces
for tool_call in response.tool_calls:
    if tool_call.function.name == "search_shops":
        # Forward to the Gateway MCP (see next step)
        # ...

Step 4: Function Implementation — Forward to MCP

Each function forwards the arguments the model produced (plus the current user’s consent_grant_id) to the corresponding tool through your MCP client. Agent identity is carried by the API Key at the MCP connection layer; consent_grant_id is passed as a tool parameter:

import json

def call_gateway_tool(mcp_client, tool_name, tool_args, consent_grant_id):
    """Call one tool through a connected Gateway MCP client.
    mcp_client is already connected to
    https://eleme-gateway.hicaspian.com/mcp/v1 (Streamable HTTP)
    with Authorization: Bearer clw_..."""
    # Business tools carry the consent_grant_id parameter;
    # binding tools request_user_bind / verify_user_bind are exempt
    # (they are the entry point for obtaining authorization).
    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):
    """Execute one tool call the model produced, forwarding it to 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)

Tool names, parameters, and response shapes are identical to MCP — the wrapper only “forwards the model’s tool calls to the gateway.” Full fields: Quote Cart · Preview Order · Create Order.

Comparison and Selection

Dimension	MCP (recommended)	Self-built wrapper (Function Calling)
Applicable Platforms	Claude Desktop, Cursor, and frameworks that support remote MCP	OpenAI-compatible frameworks that don’t support remote MCP yet
Configuration Complexity	Very low (JSON config)	Medium (define schemas yourself and forward to MCP)
Tool Discovery	Automatic	Manual (declare each tool per the contract)
Learning Cost	Low	Medium
Production Ready	Yes	Yes

Recommendation:

MCP: The recommended path. When your client/framework supports remote MCP, configure one server and tools are auto-discovered with zero boilerplate.
Self-built wrapper (Function Calling): Only when your platform doesn’t support remote MCP yet. Declare function tools against the same tool contract and forward to MCP in the implementation; you can switch smoothly to MCP once the platform supports it.

Overview

Integration

Guides

Authorization

Shops

Addresses

Order

Payment

Quick Start

MCP (recommended)

Self-built wrapper (Function Calling)

MCP Protocol

Step 1: Get API Key

Step 2: Configure MCP Server

Step 4: Call Gateway Skills

Self-built Wrapper (Function Calling)

Step 1: Get API Key

Step 2: User Authorization

Step 3: Register Function Tools Against the Tool Contract

Step 4: Function Implementation — Forward to MCP

Comparison and Selection

Troubleshooting

​Quick Start

MCP (recommended)

Self-built wrapper (Function Calling)

​MCP Protocol

​Step 1: Get API Key

​Step 2: Configure MCP Server

​Step 3: User Authorization (consent grant)

​Step 4: Call Gateway Skills

​Self-built Wrapper (Function Calling)

​Step 1: Get API Key

​Step 2: User Authorization

​Step 3: Register Function Tools Against the Tool Contract

​Step 4: Function Implementation — Forward to MCP

​Comparison and Selection

​Troubleshooting

Quick Start

MCP Protocol

Step 1: Get API Key

Step 2: Configure MCP Server

Step 3: User Authorization (consent grant)

Step 4: Call Gateway Skills

Self-built Wrapper (Function Calling)

Step 1: Get API Key

Step 2: User Authorization

Step 3: Register Function Tools Against the Tool Contract

Step 4: Function Implementation — Forward to MCP

Comparison and Selection

Troubleshooting