These examples show the arguments a client sends and what the server answers. An MCP client builds the JSON-RPC messages itself, so most show only params and the result. Records in answers are trimmed to the fields that matter: each tool’s page has the whole answer.
A raw call over HTTP
A tools/call on the 2026-07-28 protocol, sent to https://mcp.sherpo.io (the /mcp path works the same). The access token comes from signing in.
Every request sends MCP-Protocol-Version and Mcp-Method, and a tools/call also sends Mcp-Name, matching the body’s name. In params._meta, protocolVersion and clientCapabilities are required, and clientInfo is optional. Accept is needed only on the 2025-era path, which must send Accept: application/json, text/event-stream (see Connect your agent).
POST /mcp HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: list_products{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_products",
"arguments": { "query": { "limit": 1 } },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}The answer is JSON, with the result as structuredContent and the same JSON as text:
HTTP/1.1 200 OK
Content-Type: application/json{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"items\":[{\"id\":\"9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80\",\"slug\":\"intro-course\",\"title\":\"Intro course\",\"status\":\"published\"}],\"cursor\":\"Kq7vX2mPzR4tB9wNc3Ld\"}"
}
],
"structuredContent": {
"items": [
{
"id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
"slug": "intro-course",
"title": "Intro course",
"status": "published"
}
],
"cursor": "Kq7vX2mPzR4tB9wNc3Ld"
}
}
}A call without a valid token answers 401 instead, and one the connection lacks the scope for answers 403. See Errors.
Listing and paging
The published courses, newest first, two at a time, with the total:
{
"name": "list_products",
"arguments": {
"query": {
"filter": { "status": "published", "category": "course" },
"sort": { "name": "created", "direction": "desc" },
"limit": 2,
"count": true
}
}
}{
"items": [
{
"id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
"slug": "intro-course",
"title": "Intro course",
"category": "course",
"status": "published",
"created_at": "2026-10-28T09:12:00.000Z"
},
{
"id": "e5a83f19-2c6d-4b07-9f1e-7d4c0a8b2e56",
"slug": "spring-workshop",
"title": "Spring workshop",
"category": "course",
"status": "published",
"created_at": "2026-09-14T16:40:00.000Z"
}
],
"cursor": "Wf8sJ1nQ6yHk0eUa5ZrT",
"total": 3
}The next page sends the same query with the cursor:
{
"name": "list_products",
"arguments": {
"query": {
"filter": { "status": "published", "category": "course" },
"sort": { "name": "created", "direction": "desc" },
"limit": 2,
"cursor": "Wf8sJ1nQ6yHk0eUa5ZrT"
}
}
}{
"items": [
{
"id": "17c4d9e2-8a3b-4f60-b1d7-5e9a2c0f4b38",
"slug": "pottery-basics",
"title": "Pottery basics",
"category": "course",
"status": "published",
"created_at": "2026-06-02T11:05:00.000Z"
}
],
"cursor": null
}A null cursor is the last page. The cursor is opaque: pass it back as it is.
Naming the store
A connection reaching two stores names one in every store tool:
{ "name": "get_store", "arguments": { "store": "a7f2c915-4e8b-4d36-b0a1-8c5e3f9d2b47" } }{
"id": "a7f2c915-4e8b-4d36-b0a1-8c5e3f9d2b47",
"name": "Clay studio",
"currency": "EUR",
"time_zone": "Europe/Rome"
}Without store, the same call is a tool error:
{
"isError": true,
"content": [{ "type": "text", "text": "An argument is malformed. At [\"store\"]: required. (invalid)" }],
"structuredContent": {
"code": "invalid",
"context": { "path": ["store"], "reason": "required" }
}
}How a launch did
To see how a product launched on 1 November did in its first week, read product_traffic_stats for the week, which also answers the week before:
{
"name": "product_traffic_stats",
"arguments": {
"product": { "slug": "spring-workshop" },
"from": "2026-11-01",
"to": "2026-11-07"
}
}{
"time_zone": "Europe/Rome",
"from": "2026-11-01",
"to": "2026-11-07",
"previous_range": { "from": "2026-10-25", "to": "2026-10-31" },
"rolled_through": "2026-11-14",
"covered_from": "2026-10-20",
"product_views": { "current": 1840, "previous": 95 },
"checkouts_started": { "current": 212, "previous": 4 },
"orders": { "current": 61, "previous": 1 },
"rates": {
"current": { "view_to_checkout": 0.1152, "checkout_to_order": 0.2877, "view_to_order": 0.0332 },
"previous": { "view_to_checkout": 0.0421, "checkout_to_order": 0.25, "view_to_order": 0.0105 }
},
"estimated": false,
"visitors": { "current": 1210, "previous": 71 },
"by_channel": [
{ "channel": "web", "views": { "current": 1702, "previous": 95 }, "visitors": { "current": 1133, "previous": 71 }, "estimated": false },
{ "channel": "mcp", "views": { "current": 138, "previous": 0 }, "visitors": { "current": 77, "previous": 0 }, "estimated": false }
]
}visitors are each day’s unique visitors added up, since no visitor is followed from one day to the next. rolled_through is the last day counted: later days count nothing yet, and a span before covered_from answers its figures as null. traffic_stats and conversion_stats answer the same for the whole store, by channel, country and product.
What a customer would pay
To check what a customer would be charged for a course with a code before announcing it, call simulate_checkout. It buys nothing and uses no coupon:
{
"name": "simulate_checkout",
"arguments": {
"customer": { "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918" },
"product": { "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42" },
"coupon": "SPRING10"
}
}{
"at": "2026-11-16T10:30:00.000Z",
"customer": { "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918" },
"product": { "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42" },
"coupon": "SPRING10",
"quantity": 1,
"owned": null,
"prices": [
{
"price": { "id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d", "tier": { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "rank": 1, "name": "Course" }, "kind": "one_time", "period": null, "title": null, "currency": "eur", "exponent": 2, "amount": 4900 },
"verdict": { "status": "charged", "mode": "purchase", "unit": 4410, "quantity": 1, "total": 4410 },
"mode": "purchase",
"list": 4900,
"discounted": 4410,
"discount": { "applied": "coupon", "automatic": null, "coupon": { "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "name": "Spring sale", "code": "SPRING10", "discounted": 4410 } },
"coupon": { "status": "applied" },
"upgrade": null,
"minimum": { "amount": 50, "approximate": false, "waived": null },
"recurring": null
}
]
}Leave customer out to price for a new customer. Naming a customer needs customer:read, and a coupon discount:read. A refused price answers "verdict": { "status": "refused", "reason": ... }, and coupon.status says why a code doesn’t apply. Simulate an order explains every field.
A conflict
Publishing a product that is already published:
{ "name": "publish_product", "arguments": { "product": { "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80" } } }{
"isError": true,
"content": [{ "type": "text", "text": "The call clashes with the current state. (conflict)" }],
"structuredContent": {
"code": "conflict",
"context": { "field": "status", "current": "published" }
}
}The product is already as the call wanted, so there is nothing to retry. context.current is its status now.
Seeing a body rendered
Reading a page’s draft:
{ "name": "read_body", "arguments": { "target": { "kind": "page", "id": "4f1c9a2e-7b3d-4e60-a8f5-2c9d0b6e1a73" }, "staged": true } }The store’s home is read the same way, with { "kind": "store" } as the target.
{
"attachment": { "id": "8d2a6f13-5c4e-4b97-9e0a-1f7c3b5d2e86" },
"asset": { "id": "c3e7b1a9-2f6d-4085-b4c2-9a1e5d7f3b20" },
"mime": "application/vnd.sherpo.blocks+json",
"content": "{\"blocks\":[…]}",
"files": { … },
"preview": {
"url": "https://…/about?preview=…",
"expires_at": "2026-11-03T15:30:12.000Z"
}
}preview.url opens the page as a visitor sees it, draft included, until expires_at and with no sign-in, so it can be opened in a browser or a headless renderer, at desktop and phone widths and in light and dark, to check how it looks. set_body answers one too. Previews says what a link opens and when it is null.
Bulk, with one item refused
Deleting two products, one of which doesn’t exist:
{
"name": "bulk",
"arguments": {
"accessor": "deleteProduct",
"items": [
{ "product": { "id": "17c4d9e2-8a3b-4f60-b1d7-5e9a2c0f4b38" } },
{ "product": { "id": "0d6b3e81-5f2a-4c97-a4e8-9b1c7f3d2a65" } }
]
}
}The call succeeds. Its first text says how many items were refused, and results holds one outcome per item, in order:
{
"content": [
{ "type": "text", "text": "1 of 2 items refused." },
{
"type": "text",
"text": "{\"results\":[{\"outcome\":\"done\"},{\"outcome\":\"refused\",\"error\":{\"code\":\"not_found\",\"detail\":{\"kind\":\"product\",\"ref\":{\"id\":\"0d6b3e81-5f2a-4c97-a4e8-9b1c7f3d2a65\"}}}}]}"
}
],
"structuredContent": {
"results": [
{ "outcome": "done" },
{
"outcome": "refused",
"error": {
"code": "not_found",
"detail": { "kind": "product", "ref": { "id": "0d6b3e81-5f2a-4c97-a4e8-9b1c7f3d2a65" } }
}
}
]
}
}A webhook
Create an endpoint for new orders. The connection needs the Everything set, and the read scopes of order.created:
{
"name": "create_webhook",
"arguments": {
"url": "https://hooks.example.com/sherpo",
"events": ["order.created"]
}
}{
"webhook": {
"id": "8e4b1d27-6c3a-4f90-b2e5-0a7d9c1f3e68",
"url": "https://hooks.example.com/sherpo",
"description": null,
"events": ["order.created"],
"enabled": true,
"connection_ended_at": null,
"created_at": "2026-11-03T14:02:11.000Z",
"updated_at": "2026-11-03T14:02:11.000Z"
},
"secret": "whsec_Qm3vT8kZp1rXw7Lc2nYb5dHs0aGf4eJu"
}Keep the secret: no call answers it again. Each delivery then carries a Sherpo-Signature header such as:
Sherpo-Signature: t=1793715637,v1=5f1c0e9a7b3d2c4e6f8a1b0c9d7e5f3a2b4c6d8e0f1a3b5c7d9e2f4a6b8c0d1eCheck it against the raw body with the verifyWebhook function from Webhooks, then act on the event once per id:
const body = await request.text();
const signature = request.headers.get('Sherpo-Signature') ?? '';
if (!(await verifyWebhook(env.SHERPO_WEBHOOK_SECRET, body, signature)))
return new Response('Bad signature', { status: 400 });
const event = JSON.parse(body);
// Record event.id so a repeated delivery changes nothing.
return new Response(null, { status: 204 });Uploading a file
A 480 KB PDF for a private download, in three steps.
Reserve the file:
{ "name": "create_upload", "arguments": { "enforcement": "signed", "name": "workbook", "title": "Workbook", "mime": "application/pdf", "bytes": 482113 } }{ "asset": { "id": "3c9a1f60-7b2d-4e85-a0c4-6d8e2f1b9a73", "name": "workbook", "title": "Workbook", "mime": "application/pdf", "bytes": 482113, "enforcement": "signed", "status": "pending" }, "upload": { "url": "https://…", "method": "PUT", "headers": { "content-type": "application/pdf", "content-length": "482113" }, "expires_at": "2026-11-03T14:21:00.000Z" } }upload.headersis trimmed here: send every header it lists.Send the bytes, before
expires_at:PUT <upload.url> Content-Type: application/pdf Content-Length: 482113 <the file's bytes>Mark it done:
{ "name": "complete_upload", "arguments": { "asset": { "id": "3c9a1f60-7b2d-4e85-a0c4-6d8e2f1b9a73" } } }It answers the file. Attach it where it belongs, for example with
attach_asset.
A discount after a purchase
Give every buyer of the intro course 20% off the workshop’s price for the rest of the year:
{
"name": "create_automation",
"arguments": {
"name": "Workshop discount for course buyers",
"trigger": { "kind": "product.purchased", "product": { "slug": "intro-course" } },
"action": {
"kind": "price.adjust",
"price": { "id": "c41e8b2a-9d07-4f3c-8a65-3b0f7e2d1c94" },
"variable_percent": 20,
"window": { "starts_at": "2026-11-03T00:00:00Z", "ends_at": "2026-12-31T23:59:59Z" }
}
}
}The connection needs automation:write, discount:write, price:read and product:read. It answers the automation:
{
"id": "6f1d8a3c-2e9b-4c75-b0a4-1d7e5c3f9b28",
"name": "Workshop discount for course buyers",
"trigger": {
"kind": "product.purchased",
"product_id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
"price_id": null,
"discount_id": null,
"product": {
"id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
"slug": "intro-course",
"path": "/p/intro-course",
"url": "https://shop.example.com/p/intro-course",
"title": "Intro course",
"category": "course",
"deleted": false
}
},
"action": {
"kind": "price.adjust",
"price_id": "c41e8b2a-9d07-4f3c-8a65-3b0f7e2d1c94",
"product_id": "e5a83f19-2c6d-4b07-9f1e-7d4c0a8b2e56",
"fixed_cents": null,
"variable_percent": 20,
"window": { "starts_at": "2026-11-03T00:00:00.000Z", "ends_at": "2026-12-31T23:59:59.000Z" },
"product": {
"id": "e5a83f19-2c6d-4b07-9f1e-7d4c0a8b2e56",
"slug": "spring-workshop",
"path": "/p/spring-workshop",
"url": "https://shop.example.com/p/spring-workshop",
"title": "Spring workshop",
"category": "course",
"deleted": false
}
},
"paused_at": null,
"token_id": "b7d40e2c-9a15-4f83-8c6e-2f0a1d9b5e47",
"created_at": "2026-11-03T14:30:12.000Z",
"ended": false
}token_id is the token of the connection that created it, in this store’s business, and ended turns true once a price.adjust window is over.
From then on, each purchase of the course makes the buyer a single-use code for the workshop, and sends discounts.unlocked. list_automation_runs shows each run and its outcome.
Move an event from Luma
With Luma’s own MCP server connected beside this one, your AI can read an event there and recreate it here: the product with create_product, its session with create_event_session, its ticket types with create_tier and create_price, its questions with create_product_question, then each guest going with record_order, by their email, and their answers with set_customer_answers. Migrate from Luma has a request to start from and what guests receive.