Quick Start - Clawdot虾点·文档中心

Clawdot Gateway exposes food-delivery capabilities to AI Agents as MCP tools. This guide first connects you to MCP, then walks a single chain of tool calls to run a complete order from scratch.

1. Connect over MCP

The gateway serves MCP over Streamable HTTP (FastMCP):

Endpoint: https://eleme-gateway.hicaspian.com/mcp/v1
Transport: Streamable HTTP
Connection-layer auth: every MCP request carries the header Authorization: Bearer clw_your_api_key

Create an Agent and enable the delivery capability in the Clawdot Console to obtain your API Key (clw_ prefix). Configure it in your MCP client:

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

Once connected, your Agent can see all 24 delivery MCP tools. Errand (same-city delivery-run) is a separate endpoint with 19 tools of its own — see Errand MCP.

Two-layer identity: the connection-layer API Key (clw_ prefix) identifies your Agent and is required on every MCP request; the consent grant (cg_ prefix) identifies an authorized food-delivery user and is passed as the business-tool parameter consent_grant_id (not as a header). The binding tools request_user_bind / verify_user_bind are the exception — they are the entry point for obtaining authorization and take no consent_grant_id. See Authentication.

2. Place an order with MCP tools

Examples are given as tool name + JSON parameters. Except for the binding tools, every business tool carries consent_grant_id.

Bind user authorization

Placing an order acts on behalf of a real food-delivery user, so have them authorize first (SMS code mode). The binding tools need only the Agent identity (connection-layer API Key) and take no consent_grant_id.

// Tool: request_user_bind — start binding; the user receives an SMS code
{
  "phone": "18800000000",
  "auth_type": "sms"
}
// -> { "bind_id": "...", "expires_in": ..., "masked_phone": "188****0000" }

// Tool: verify_user_bind — confirm with the code the user gave you; mints consent_grant_id
{
  "auth_type": "sms",
  "bind_id": "<bind_id from step 1>",
  "code": "123456"
}
// -> { "bound": true, "consent_grant_id": "cg_...", "scopes": [...], "expires_at": "..." }

Once you have consent_grant_id, every business tool call below carries it.

H5 mode is also supported: request_user_bind(auth_type="h5") returns h5_url; the user opens it to authorize, then you call verify_user_bind(auth_type="h5", request_id) and poll until you get consent_grant_id. See Request Binding.

Choose a delivery address

Pin down “where to deliver” first; obtain address_id, then search shops that can deliver to it.

// Tool: search_addresses — search addresses; get suggestions (each with a token)
{
  "consent_grant_id": "cg_your_consent_grant",
  "keyword": "People's Square, Huangpu, Shanghai"
}
// -> { "suggestions": [ { "token": "...", ... } ] }

// Tool: select_address — select/save the address; get address_id
// Contact info is required when creating a new address from a suggestion
{
  "consent_grant_id": "cg_your_consent_grant",
  "suggestion_token": "<a suggestion's token from above>",
  "contact_name": "John Doe",
  "contact_phone": "13800000000",
  "address_detail": "Bldg 3, Room 101"
}
// -> { "address_id": "...", "display_name": "...", "lat": ..., "lng": ... }

You can also use an existing address’s address_id directly. This address_id is used both to search shops next and for later quoting / previewing.

Search shops

// Tool: search_shops
{
  "consent_grant_id": "cg_your_consent_grant",
  "address_id": "<from select>",
  "keyword": "Luckin Coffee"
}
// -> { "shops": [ { "shop_id": "...", "cart_id": "...", "name": "...", ... } ], "next_offset": ... }

Search shops that can deliver to the chosen address (provide at least one of address_id or lat/lng). Each shop carries a shop_id and a cart_id (the cart_id encapsulates the shop and delivery coordinates; pass it back as-is in later steps). Omit keyword to browse nearby (up to 20 shops).

Browse the menu, pick items

// Tool: get_shop_menu
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<from search>",
  "cart_id": "<from search>"
}
// -> items[]: each carries item_id / sku_id / ingredient_options; has_more signals if there is more

Supports keyword / limit / offset for progressive loading. Note the item_id and sku_id of what you want to buy.

Quote the cart

// Tool: quote_cart
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<from search>",
  "cart_id": "<from search>",
  "address_id": "<from select>",
  "items": [{"item_id": "<from menu>", "sku_id": "<from menu>", "quantity": 1}]
}
// -> { "quote_id": "...", "can_checkout": true, "payable_price": 1500 }

All amount fields are in cents (integers); 1500 means ¥15.00.

Preview the order

// Tool: preview_order
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<from search>",
  "cart_id": "<from search>",
  "address_id": "<from select>",
  "items": [{"item_id": "<from menu>", "sku_id": "<from menu>", "quantity": 1}],
  "quote_id": "<from quote>"
}
// -> { "preview_id": "prv_...", "confirmation_token": "cf_...", "price": {...}, "available_coupons": [...] }

Coupons usable on the current order are the returned available_coupons. To apply a coupon, pick available_coupons[].coupon_id and call preview_order again with coupon_ids=[...] to re-price (the account-level coupon list is available via list_coupons).

Place the order

Use the preview_id + confirmation_token returned by the preview (confirmation_token is the idempotency key):

// Tool: create_order
{
  "consent_grant_id": "cg_your_consent_grant",
  "preview_id": "prv_...",
  "confirmation_token": "cf_..."
}
// -> { "order_id": "ord_...", "status": "...", "payment_action": {...} }

You may pass an optional callback_url: every status change on the order is pushed as a callback, and the payment-outcome one carries event=order_payment.

Check the order

After placing the order, you can check its current status and details anytime.

// Tool: get_order_status — check the order status
{
  "consent_grant_id": "cg_your_consent_grant",
  "order_id": "ord_..."
}
// -> { "status": "...", "status_text": "...", ... }

No-password payment signing (account-level, one-time): no-password payment requires the user to sign once; afterwards subsequent no-password orders are charged automatically. It is an account-level, one-time prerequisite — not bound to any single order and not done per order — so it is independent of the order chain above. Use get_sign_action(consent_grant_id, return_url) (takes no order_id) to get the H5 signing link for the user to complete, then check signing progress with get_sign_status. See Initiate No-Password Signing.

The full chain at a glance

select_address (-> address_id) -> search_shops (with address_id, -> shop_id + cart_id) -> get_shop_menu (-> item_id / sku_id) -> quote_cart (-> quote_id) -> preview_order (-> preview_id + confirmation_token) -> create_order (-> order_id) -> get_order_status Every cross-step ID (shop_id / cart_id / address_id / preview_id …) is issued by the gateway and passed back as-is — never construct them yourself or mix them across chains.

Next steps

MCP Tools

Full request / response for the 24 delivery MCP tools

Authentication

API Key + consent grant in detail

Order Flow

End-to-end order and payment sequence

Error Handling

Unified error codes and handling

​1. Connect over MCP

​2. Place an order with MCP tools

​The full chain at a glance

​Next steps

MCP Tools

Authentication

Order Flow

Error Handling

1. Connect over MCP

2. Place an order with MCP tools

The full chain at a glance

Next steps