---
title: "Examples"
description: "Real requests to a store's customer MCP server and what it answers, from listing tools to taking a quiz."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

Each example below is a request to the store `shop.example.com` and the answer it gets, captured from a test store (names and ids changed to read better). An MCP client sends these for you; they're here for building a client, and to show what an assistant sees. Each tool's full arguments and answer are on its [reference page](/customer-mcp/tools).

## A request over HTTP

Every request is one `POST` to the endpoint with the customer's token (see [Sign-in](/customer-mcp/sign-in#for-developers)). On MCP's 2026-07-28 revision, the method and the tool's name go in headers too, and the client describes itself in `_meta`:

```sh
curl https://shop.example.com/mcp \
  -H 'authorization: Bearer ACCESS_TOKEN' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: tools/call' \
  -H 'mcp-name: get_profile' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_profile",
      "arguments": {},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "my-app", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'
```

The examples below show the JSON-RPC message alone; each is sent the same way. An answer's `result` also carries `resultType` and `_meta` with the server's name and the store's icons, left out below.

## Read the customer's profile

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_profile",
    "arguments": {}
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"a1b2c3d4e5f60718293a4b5c\",\"display_name\":null,\"locale\":null,\"country\":\"IT\",\"created_at\":\"2023-11-14T22:18:20.000Z\",\"contacts\":[{\"kind\":\"email\",\"value\":\"alex@example.com\",\"verified_at\":\"2023-11-14T22:18:20.000Z\"}]}"
      }
    ],
    "structuredContent": {
      "id": "a1b2c3d4e5f60718293a4b5c",
      "display_name": null,
      "locale": null,
      "country": "IT",
      "created_at": "2023-11-14T22:18:20.000Z",
      "contacts": [
        {
          "kind": "email",
          "value": "alex@example.com",
          "verified_at": "2023-11-14T22:18:20.000Z"
        }
      ]
    }
  }
}
```

`content` holds the same answer as text, for a model that reads text alone; `structuredContent` holds it as JSON, valid against the tool's output schema.

## List a course's lessons

`list_entries` pages a product's lessons, with what each one needs (`requires`), whether it's open to the customer (`access`) and whether they completed it (`completed_at`):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_entries",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "query": {
        "limit": 2
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"id\":\"4b9e1f7a2c3d5e6f7a8b9c0d\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"slug\":\"welcome\",\"path\":\"/p/photography-basics/welcome\",\"url\":\"https://shop.example.com/p/photography-basics/welcome\",\"title\":\"Welcome\",\"subtitle\":null,\"section\":\"Basics\",\"author\":null,\"tags\":[],\"preview\":null,\"position\":0,\"published_at\":\"2023-11-14T22:20:20.000Z\",\"unlisted_at\":null,\"created_at\":\"2023-11-14T22:20:20.000Z\",\"updated_at\":\"2023-11-14T22:20:20.000Z\",\"settings\":{\"ai_generated\":false},\"access\":\"unlocked\",\"requires\":{\"kind\":\"tier\",\"rank\":2},\"opens_at\":null,\"poster\":null,\"files\":{},\"completed_at\":\"2023-11-14T22:27:00.000Z\",\"duration\":null,\"words\":2,\"has_quiz\":true,\"has_certificate\":true,\"quiz_score\":null,\"media\":{\"duration\":null,\"slides\":null,\"files\":0,\"links\":0}},{\"id\":\"5c0f2a8b3d4e6f7a8b9c0d1e\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"slug\":\"light-and-exposure\",\"path\":\"/p/photography-basics/light-and-exposure\",\"url\":\"https://shop.example.com/p/photography-basics/light-and-exposure\",\"title\":\"Light and exposure\",\"subtitle\":null,\"section\":null,\"author\":null,\"tags\":[],\"preview\":null,\"position\":1,\"published_at\":\"2023-11-14T22:20:21.000Z\",\"unlisted_at\":null,\"created_at\":\"2023-11-14T22:20:21.000Z\",\"updated_at\":\"2023-11-14T22:20:21.000Z\",\"settings\":{\"ai_generated\":false},\"access\":\"unlocked\",\"requires\":{\"kind\":\"tier\",\"rank\":2},\"opens_at\":null,\"poster\":null,\"files\":{},\"completed_at\":null,\"duration\":null,\"words\":4,\"has_quiz\":true,\"has_certificate\":true,\"quiz_score\":80,\"media\":{\"duration\":null,\"slides\":null,\"files\":0,\"links\":0}}],\"cursor\":\"eyJrIjpbMSwiNWMwZjJhOGIzZDRlNmY3YThiOWMwZDFlIl0sInEiOiJwUUtuZ3lpOGF5X2Y1MHJCIn0\"}"
      }
    ],
    "structuredContent": {
      "items": [
        {
          "id": "4b9e1f7a2c3d5e6f7a8b9c0d",
          "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
          "slug": "welcome",
          "path": "/p/photography-basics/welcome",
          "url": "https://shop.example.com/p/photography-basics/welcome",
          "title": "Welcome",
          "subtitle": null,
          "section": "Basics",
          "author": null,
          "tags": [],
          "preview": null,
          "position": 0,
          "published_at": "2023-11-14T22:20:20.000Z",
          "unlisted_at": null,
          "created_at": "2023-11-14T22:20:20.000Z",
          "updated_at": "2023-11-14T22:20:20.000Z",
          "settings": {
            "ai_generated": false
          },
          "access": "unlocked",
          "requires": {
            "kind": "tier",
            "rank": 2
          },
          "opens_at": null,
          "poster": null,
          "files": {},
          "completed_at": "2023-11-14T22:27:00.000Z",
          "duration": null,
          "words": 2,
          "has_quiz": true,
          "has_certificate": true,
          "quiz_score": null,
          "media": {
            "duration": null,
            "slides": null,
            "files": 0,
            "links": 0
          }
        },
        {
          "id": "5c0f2a8b3d4e6f7a8b9c0d1e",
          "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
          "slug": "light-and-exposure",
          "path": "/p/photography-basics/light-and-exposure",
          "url": "https://shop.example.com/p/photography-basics/light-and-exposure",
          "title": "Light and exposure",
          "subtitle": null,
          "section": null,
          "author": null,
          "tags": [],
          "preview": null,
          "position": 1,
          "published_at": "2023-11-14T22:20:21.000Z",
          "unlisted_at": null,
          "created_at": "2023-11-14T22:20:21.000Z",
          "updated_at": "2023-11-14T22:20:21.000Z",
          "settings": {
            "ai_generated": false
          },
          "access": "unlocked",
          "requires": {
            "kind": "tier",
            "rank": 2
          },
          "opens_at": null,
          "poster": null,
          "files": {},
          "completed_at": null,
          "duration": null,
          "words": 4,
          "has_quiz": true,
          "has_certificate": true,
          "quiz_score": 80,
          "media": {
            "duration": null,
            "slides": null,
            "files": 0,
            "links": 0
          }
        }
      ],
      "cursor": "eyJrIjpbMSwiNWMwZjJhOGIzZDRlNmY3YThiOWMwZDFlIl0sInEiOiJwUUtuZ3lpOGF5X2Y1MHJCIn0"
    }
  }
}
```

Pass `cursor` back as `query.cursor`, with the same query otherwise, for the next page:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_entries",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "query": {
        "limit": 2,
        "cursor": "eyJrIjpbMSwiNWMwZjJhOGIzZDRlNmY3YThiOWMwZDFlIl0sInEiOiJwUUtuZ3lpOGF5X2Y1MHJCIn0"
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"id\":\"6d1a3b9c4e5f7a8b9c0d1e2f\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"slug\":\"composition\",\"path\":\"/p/photography-basics/composition\",\"url\":\"https://shop.example.com/p/photography-basics/composition\",\"title\":\"Composition\",\"subtitle\":null,\"section\":null,\"author\":null,\"tags\":[],\"preview\":\"<rich-text version=\\\"1\\\"><p>Free preview.</p></rich-text>\",\"position\":2,\"published_at\":\"2023-11-14T22:20:22.000Z\",\"unlisted_at\":null,\"created_at\":\"2023-11-14T22:20:22.000Z\",\"updated_at\":\"2023-11-14T22:20:22.000Z\",\"settings\":{\"ai_generated\":false},\"access\":\"unlocked\",\"requires\":{\"kind\":\"everyone\"},\"opens_at\":null,\"poster\":null,\"files\":{},\"completed_at\":null,\"duration\":null,\"words\":null,\"has_quiz\":false,\"has_certificate\":false,\"quiz_score\":null,\"media\":{\"duration\":null,\"slides\":null,\"files\":0,\"links\":0}}],\"cursor\":null}"
      }
    ],
    "structuredContent": {
      "items": [
        {
          "id": "6d1a3b9c4e5f7a8b9c0d1e2f",
          "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
          "slug": "composition",
          "path": "/p/photography-basics/composition",
          "url": "https://shop.example.com/p/photography-basics/composition",
          "title": "Composition",
          "subtitle": null,
          "section": null,
          "author": null,
          "tags": [],
          "preview": "<rich-text version=\"1\"><p>Free preview.</p></rich-text>",
          "position": 2,
          "published_at": "2023-11-14T22:20:22.000Z",
          "unlisted_at": null,
          "created_at": "2023-11-14T22:20:22.000Z",
          "updated_at": "2023-11-14T22:20:22.000Z",
          "settings": {
            "ai_generated": false
          },
          "access": "unlocked",
          "requires": {
            "kind": "everyone"
          },
          "opens_at": null,
          "poster": null,
          "files": {},
          "completed_at": null,
          "duration": null,
          "words": null,
          "has_quiz": false,
          "has_certificate": false,
          "quiz_score": null,
          "media": {
            "duration": null,
            "slides": null,
            "files": 0,
            "links": 0
          }
        }
      ],
      "cursor": null
    }
  }
}
```

A `null` cursor is the last page. A cursor works only with the query it came from.

## Mark a lesson complete

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "complete_entry",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "entry": {
        "id": "4b9e1f7a2c3d5e6f7a8b9c0d"
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"entry_id\":\"4b9e1f7a2c3d5e6f7a8b9c0d\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"completed_at\":\"2026-11-03T03:36:41.000Z\",\"certificates\":[]}"
      }
    ],
    "structuredContent": {
      "entry_id": "4b9e1f7a2c3d5e6f7a8b9c0d",
      "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
      "completed_at": "2026-11-03T03:36:41.000Z",
      "certificates": []
    }
  }
}
```

`certificates` lists any certificate the completion earned.

## Read a video's or audio file's chapters, summary and transcript

`get_media_outputs` reads what the store published for a lesson's video or audio file, by its attachment id (from the lesson's `files` or `attachments`):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_media_outputs",
    "arguments": {
      "attachment": "9a8b7c6d5e4f30211a2b3c4d",
      "kinds": [
        "chapters",
        "summary",
        "transcript"
      ]
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"chapters\":[{\"start\":0,\"title\":\"Why light matters\"},{\"start\":95,\"title\":\"The exposure triangle\"}],\"summary\":{\"summary\":\"How light, aperture, shutter speed and ISO work together.\",\"key_points\":[\"Aperture sets depth of field.\",\"Shutter speed freezes or blurs motion.\",\"ISO trades brightness for noise.\"]},\"transcript\":\"Welcome back. In this lesson we look at light...\",\"unreadable\":[]}"
      }
    ],
    "structuredContent": {
      "chapters": [
        {
          "start": 0,
          "title": "Why light matters"
        },
        {
          "start": 95,
          "title": "The exposure triangle"
        }
      ],
      "summary": {
        "summary": "How light, aperture, shutter speed and ISO work together.",
        "key_points": [
          "Aperture sets depth of field.",
          "Shutter speed freezes or blurs motion.",
          "ISO trades brightness for noise."
        ]
      },
      "transcript": "Welcome back. In this lesson we look at light...",
      "unreadable": []
    }
  }
}
```

## Take a quiz

Start an attempt on a lesson's quiz, named with its product and lesson, which answers the questions without their answers:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "start_attempt",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "entry": {
        "id": "4b9e1f7a2c3d5e6f7a8b9c0d"
      },
      "quiz": {
        "id": "e9f0a1b2c3d4e5f60718293a"
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"attempt\":{\"id\":\"e17c86de-c1a8-48f5-93f8-5dc3fd2f15bd\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"quiz_id\":\"e9f0a1b2c3d4e5f60718293a\",\"entry_id\":\"4b9e1f7a2c3d5e6f7a8b9c0d\",\"attempt\":1,\"status\":\"started\",\"score\":null,\"correct\":null,\"started_at\":\"2026-11-03T03:36:42.000Z\",\"finished_at\":null,\"access\":\"unlocked\"},\"questions\":[{\"type\":\"multiple_choice\",\"id\":\"q1\",\"question\":\"Which setting controls depth of field?\",\"content\":null,\"options\":[{\"id\":\"a\",\"text\":\"Shutter speed\"},{\"id\":\"b\",\"text\":\"Aperture\"}],\"min\":null,\"max\":null,\"weight\":2,\"hint\":null},{\"type\":\"true_false\",\"id\":\"q2\",\"question\":\"A higher ISO adds noise.\",\"content\":null,\"options\":null,\"min\":null,\"max\":null,\"weight\":1,\"hint\":null}],\"attachments\":[],\"files\":{},\"answers\":{}}"
      }
    ],
    "structuredContent": {
      "attempt": {
        "id": "e17c86de-c1a8-48f5-93f8-5dc3fd2f15bd",
        "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
        "quiz_id": "e9f0a1b2c3d4e5f60718293a",
        "entry_id": "4b9e1f7a2c3d5e6f7a8b9c0d",
        "attempt": 1,
        "status": "started",
        "score": null,
        "correct": null,
        "started_at": "2026-11-03T03:36:42.000Z",
        "finished_at": null,
        "access": "unlocked"
      },
      "questions": [
        {
          "type": "multiple_choice",
          "id": "q1",
          "question": "Which setting controls depth of field?",
          "content": null,
          "options": [
            {
              "id": "a",
              "text": "Shutter speed"
            },
            {
              "id": "b",
              "text": "Aperture"
            }
          ],
          "min": null,
          "max": null,
          "weight": 2,
          "hint": null
        },
        {
          "type": "true_false",
          "id": "q2",
          "question": "A higher ISO adds noise.",
          "content": null,
          "options": null,
          "min": null,
          "max": null,
          "weight": 1,
          "hint": null
        }
      ],
      "attachments": [],
      "files": {},
      "answers": {}
    }
  }
}
```

Then submit the answers, keyed by question id. The attempt is graded at once, and the answer shows each result, with the key where the quiz shows it, and any certificate the score earned:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "submit_attempt",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "attempt": {
        "id": "e17c86de-c1a8-48f5-93f8-5dc3fd2f15bd"
      },
      "answers": {
        "q1": "b",
        "q2": true
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"attempt\":{\"id\":\"e17c86de-c1a8-48f5-93f8-5dc3fd2f15bd\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"quiz_id\":\"e9f0a1b2c3d4e5f60718293a\",\"entry_id\":\"4b9e1f7a2c3d5e6f7a8b9c0d\",\"attempt\":1,\"status\":\"passed\",\"score\":100,\"correct\":2,\"started_at\":\"2026-11-03T03:36:42.000Z\",\"finished_at\":\"2026-11-03T03:36:42.000Z\",\"access\":\"unlocked\"},\"score\":100,\"correct\":2,\"total\":2,\"results\":[{\"question_id\":\"q1\",\"answer\":\"b\",\"correct\":true,\"key\":{\"correct_option_id\":\"b\",\"correct_answer\":null,\"correct_value\":null,\"accepted_answers\":[],\"explanation\":\"Aperture sets how much of the scene is sharp.\"}},{\"question_id\":\"q2\",\"answer\":true,\"correct\":true,\"key\":{\"correct_option_id\":null,\"correct_answer\":true,\"correct_value\":null,\"accepted_answers\":[],\"explanation\":null}}],\"certificate\":{\"id\":\"1f2e3d4c5b6a79880a9b8c7d\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"certificate_id\":\"2a3b4c5d6e7f80910a1b2c3d\",\"score\":100,\"attempt\":1,\"issued_at\":\"2026-11-03T03:36:42.000Z\"},\"certificates\":[]}"
      }
    ],
    "structuredContent": {
      "attempt": {
        "id": "e17c86de-c1a8-48f5-93f8-5dc3fd2f15bd",
        "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
        "quiz_id": "e9f0a1b2c3d4e5f60718293a",
        "entry_id": "4b9e1f7a2c3d5e6f7a8b9c0d",
        "attempt": 1,
        "status": "passed",
        "score": 100,
        "correct": 2,
        "started_at": "2026-11-03T03:36:42.000Z",
        "finished_at": "2026-11-03T03:36:42.000Z",
        "access": "unlocked"
      },
      "score": 100,
      "correct": 2,
      "total": 2,
      "results": [
        {
          "question_id": "q1",
          "answer": "b",
          "correct": true,
          "key": {
            "correct_option_id": "b",
            "correct_answer": null,
            "correct_value": null,
            "accepted_answers": [],
            "explanation": "Aperture sets how much of the scene is sharp."
          }
        },
        {
          "question_id": "q2",
          "answer": true,
          "correct": true,
          "key": {
            "correct_option_id": null,
            "correct_answer": true,
            "correct_value": null,
            "accepted_answers": [],
            "explanation": null
          }
        }
      ],
      "certificate": {
        "id": "1f2e3d4c5b6a79880a9b8c7d",
        "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
        "certificate_id": "2a3b4c5d6e7f80910a1b2c3d",
        "score": 100,
        "attempt": 1,
        "issued_at": "2026-11-03T03:36:42.000Z"
      },
      "certificates": []
    }
  }
}
```

To keep answers without submitting, `save_attempt` saves them to the open attempt, which resumes from any device.

## Write a review

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_review",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "rating": 4,
      "notes": "Good",
      "username": "Alice"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"0a1b2c3d4e5f60718293a4b5\",\"product_id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"rating\":4,\"username\":\"Alice\",\"notes\":\"Good\",\"reply\":null,\"replied_at\":null,\"created_at\":\"2023-11-14T22:26:40.000Z\",\"updated_at\":\"2026-11-03T03:36:42.000Z\",\"mine\":true,\"hidden_at\":null}"
      }
    ],
    "structuredContent": {
      "id": "0a1b2c3d4e5f60718293a4b5",
      "product_id": "8f3c2a1d9b7e4f60a1c5d2e7",
      "rating": 4,
      "username": "Alice",
      "notes": "Good",
      "reply": null,
      "replied_at": null,
      "created_at": "2023-11-14T22:26:40.000Z",
      "updated_at": "2026-11-03T03:36:42.000Z",
      "mine": true,
      "hidden_at": null
    }
  }
}
```

## Verify a certificate

`verify_certificate` needs no scope: it checks that a certificate was issued and isn't revoked, and, given `of`, that the issue belongs to that certificate, as a certificate's verification link names it.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "verify_certificate",
    "arguments": {
      "certificate": {
        "id": "c7d8e9f0a1b2c3d4e5f60718"
      },
      "of": {
        "id": "d8e9f0a1b2c3d4e5f6071829"
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"c7d8e9f0a1b2c3d4e5f60718\",\"certificate_id\":\"d8e9f0a1b2c3d4e5f6071829\",\"issued_at\":\"2023-11-14T22:27:50.000Z\",\"score\":80,\"holder\":null,\"headline_copy\":\"Certificate of Completion\",\"title_copy\":\"Photography basics\",\"product\":{\"id\":\"8f3c2a1d9b7e4f60a1c5d2e7\",\"slug\":\"photography-basics\",\"path\":\"/p/photography-basics\",\"url\":\"https://shop.example.com/p/photography-basics\",\"title\":\"Photography basics\",\"category\":\"course\",\"deleted\":false}}"
      }
    ],
    "structuredContent": {
      "id": "c7d8e9f0a1b2c3d4e5f60718",
      "certificate_id": "d8e9f0a1b2c3d4e5f6071829",
      "issued_at": "2023-11-14T22:27:50.000Z",
      "score": 80,
      "holder": null,
      "headline_copy": "Certificate of Completion",
      "title_copy": "Photography basics",
      "product": {
        "id": "8f3c2a1d9b7e4f60a1c5d2e7",
        "slug": "photography-basics",
        "path": "/p/photography-basics",
        "url": "https://shop.example.com/p/photography-basics",
        "title": "Photography basics",
        "category": "course",
        "deleted": false
      }
    }
  }
}
```

## Run a prompt

List the prompts the customer may run:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {}
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "fe-analysis",
        "title": "Full analysis (Research)",
        "description": "Analyse a company.",
        "arguments": [
          {
            "name": "company",
            "required": true
          }
        ]
      }
    ]
  }
}
```

Then read one by its listed name, with its arguments:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "fe-analysis",
    "arguments": {
      "company": "Acme"
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "description": "Analyse a company.",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "# Analyse Acme\n\nStart with its last annual report."
        }
      }
    ]
  }
}
```

## List the tools

`tools/list` answers the tools the connection may call, 50 a page (one tool shown):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_profile",
        "title": "Read profile",
        "description": "Reads the customer's profile.\n\nNeeds the read scope.",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "additionalProperties": false
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "contacts": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "x-extensible-enum": [
                      "email",
                      "phone"
                    ]
                  },
                  "value": {
                    "type": "string"
                  },
                  "verified_at": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "kind",
                  "value",
                  "verified_at"
                ]
              }
            },
            "id": {
              "type": "string"
            },
            "display_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "locale": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "country": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "created_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "contacts",
            "id",
            "display_name",
            "locale",
            "country",
            "created_at"
          ]
        },
        "annotations": {
          "title": "Read profile",
          "readOnlyHint": true,
          "idempotentHint": true,
          "openWorldHint": false
        }
      }
    ]
  }
}
```

## Errors

A reference that matches nothing is a tool error:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {
      "product": {
        "slug": "no-such-product"
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Nothing matches the reference given. (not_found)"
      }
    ],
    "structuredContent": {
      "code": "not_found",
      "context": {
        "kind": "product",
        "ref": {
          "slug": "no-such-product"
        }
      }
    },
    "isError": true
  }
}
```

An argument out of its limits is refused as `invalid`, naming its path:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_products",
    "arguments": {
      "query": {
        "limit": 1000
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "An argument is malformed. At [\"query\",\"limit\"]: expected an integer from 1 to 100. (invalid)"
      }
    ],
    "structuredContent": {
      "code": "invalid",
      "context": {
        "path": [
          "args",
          "query",
          "limit"
        ],
        "reason": "expected an integer from 1 to 100"
      }
    },
    "isError": true
  }
}
```

A request without a token is refused before any tool runs:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://shop.example.com/.well-known/oauth-protected-resource/mcp"
```

A call the token's scopes don't cover, such as `update_profile` on a Read-only connection, is refused for the request:

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", resource_metadata="https://shop.example.com/.well-known/oauth-protected-resource/mcp"
```

[Limits and errors](/customer-mcp/limits) lists every code and status.

Source: https://docs.sherpo.io/customer-mcp/examples/index.mdx
