MCP endpoint configuration
Your MCP endpoint is the core of your UCP integration. It receives JSON-RPC 2.0 requests over HTTP POST and returns structured responses that agents use to search, build a cart and check out.
Protocol basics
MCP (Model Context Protocol) uses JSON-RPC 2.0 as its wire format. Every request is an HTTP POST to your endpoint with a JSON body containing a method name, parameters, and a request ID. Your endpoint must respond with the corresponding JSON-RPC result or error.
All requests use Content-Type: application/json and your responses should do the same.
Required methods
Your endpoint must handle at least three methods. A fourth is optional but useful for certain agent workflows:
- initialize — The protocol handshake. The client sends its
protocolVersion,clientInfoand capabilities. Respond with your ownprotocolVersion,serverInfo, and capabilities. If you return anMcp-Session-Idresponse header here, clients echo it on every subsequent request in the session (streamable-HTTP session continuity). - tools/list — Returns the full set of tools your store supports. Each tool includes a name, description, and a JSON Schema defining its input parameters. This is how agents discover what your store can do.
- tools/call — Executes a specific tool by name with the provided arguments. This is where the real work happens: searching products, managing carts, and processing checkouts.
- resources/read (optional) — Returns static or semi-static resources like store policies, shipping information, or category trees. Useful but not required for basic UCP support.
Tool names
The UCP MCP binding names the tools for each capability. These are the names agents see on UCP stores today:
- search_catalog — search products with keywords, filters and pagination
- lookup_catalog and get_product — fetch products by ID, with variants and availability
- create_cart / get_cart / update_cart / cancel_cart — build, read and drop a cart, if you declare the cart capability
- create_checkout — start a checkout session
- update_checkout — set buyer details, fulfillment and payment on a checkout
- get_checkout / cancel_checkout — read or cancel a checkout session
- complete_checkout — place the order and take payment
- get_order — read an order, if you declare the order capability
- search_locations / lookup_locations — find stores or pickup points, if you declare location search and lookup
Our test store at flowers.ucpsandbox.com/mcp lists all of these, so you can compare your tools/list with a working one.
Older Shopify-style names such as search_shop_catalog and get_product_details are still recognised.
The agent profile on each call
UCP Playground sends its agent profile with every tools/call in params._meta["ucp-agent"].profile. If your tool schemas declare a meta input property, it also puts the profile in arguments.meta. Requests are signed; see Agent identity for how to verify them.
Request and response format
A tools/call request to search for products, and the response shape:
Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_catalog",
"arguments": {
"query": "organic coffee"
},
"_meta": {
"ucp-agent": { "profile": "https://ucpplayground.com/.well-known/ucp-agent" }
}
}
}Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": { "version": "2026-08-25" },
"products": [
{ "id": "123", "title": "Ethiopian Yirgacheffe", "price_range": { "min": { "amount": 1899, "currency": "USD" } } }
]
},
"content": [
{ "type": "text", "text": "{\"products\":[{\"id\":\"123\", ...}]}" }
]
}
} Return the response payload in structuredContent. You may also mirror a serialized copy into the content array for clients that don't read structured results. UCP Playground reads structuredContent first and falls back to the text in content, so if you only send text, make it a valid JSON string.
Return product data as structured JSON, not prose. Agents read JSON far more reliably, and it removes doubt about prices, variant IDs and availability.
Error responses
When a tool call fails, return a JSON-RPC error with an appropriate code. The most common error codes are -32601 (method not found), -32602 (invalid params), and -32603 (internal error). Include a clear message so the agent can adjust, or tell the buyer what went wrong.
Something wrong on this page?