Skip to content

Examples

Real requests to a store's customer MCP server and what it answers, from listing tools to taking a quiz.

Updated

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.

A request over HTTP

Every request is one POST to the endpoint with the customer’s token (see Sign-in). 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:

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_profile",
    "arguments": {}
  }
}
{
  "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):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_entries",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "query": {
        "limit": 2
      }
    }
  }
}
{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_entries",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "query": {
        "limit": 2,
        "cursor": "eyJrIjpbMSwiNWMwZjJhOGIzZDRlNmY3YThiOWMwZDFlIl0sInEiOiJwUUtuZ3lpOGF5X2Y1MHJCIn0"
      }
    }
  }
}
{
  "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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "complete_entry",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "entry": {
        "id": "4b9e1f7a2c3d5e6f7a8b9c0d"
      }
    }
  }
}
{
  "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):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_media_outputs",
    "arguments": {
      "attachment": "9a8b7c6d5e4f30211a2b3c4d",
      "kinds": [
        "chapters",
        "summary",
        "transcript"
      ]
    }
  }
}
{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "start_attempt",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "entry": {
        "id": "4b9e1f7a2c3d5e6f7a8b9c0d"
      },
      "quiz": {
        "id": "e9f0a1b2c3d4e5f60718293a"
      }
    }
  }
}
{
  "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:

{
  "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
      }
    }
  }
}
{
  "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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_review",
    "arguments": {
      "product": {
        "slug": "photography-basics"
      },
      "rating": 4,
      "notes": "Good",
      "username": "Alice"
    }
  }
}
{
  "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.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "verify_certificate",
    "arguments": {
      "certificate": {
        "id": "c7d8e9f0a1b2c3d4e5f60718"
      },
      "of": {
        "id": "d8e9f0a1b2c3d4e5f6071829"
      }
    }
  }
}
{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {}
}
{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "fe-analysis",
    "arguments": {
      "company": "Acme"
    }
  }
}
{
  "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):

{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {
      "product": {
        "slug": "no-such-product"
      }
    }
  }
}
{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_products",
    "arguments": {
      "query": {
        "limit": 1000
      }
    }
  }
}
{
  "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/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/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 lists every code and status.

Type to search…

↑↓ navigate↵ selectEsc close