Limits
| What | Limit |
|---|---|
| Calls | 600 a minute for each connected app in each store, unless the store set another limit for that app, or a quota a day or a month. An app connected to two stores has each store’s limit. |
| A page of a list | Set with query.limit: at most 100 items, 400 for list_portfolio_snapshots. Each list’s default and maximum are in its input schema. |
tools/list |
50 tools a page, with nextCursor for the next. |
prompts/list |
Up to 100 prompts in one answer, with no paging. |
| A request’s body | 4 MiB. A larger one answers 413. |
| A private file in an answer | 8 MiB (see Files). |
| Batches | Not supported: send one JSON-RPC request per HTTP request. |
A write that fails still counts toward the limit. A call past it is refused with not_permitted and retry_after, the seconds to wait (see below). Every tool’s own limits on its arguments (lengths, ranges, how many ids a call takes) are in its input schema, on its reference page.
How the server answers
The server speaks MCP over Streamable HTTP at the store’s endpoint: one POST per request, answered with JSON. It keeps no session between requests, so there is nothing to reconnect after a pause. It speaks MCP’s 2026-07-28 revision, and answers clients on the 2025 revisions too.
Tools are listed afresh on each tools/list, filtered by the connection’s scopes: a tool its access doesn’t cover isn’t listed, and calling it anyway answers 403.
Lists
A tool that pages a list answers a page of items and a cursor (list_contacts, which answers the customer’s few contacts under result, doesn’t page): pass the cursor back as query.cursor for the next page, until it comes back null. A list may also take filters, sorts and a search of up to 200 characters, which its reference page names. While searching, an empty page with a cursor means nothing so far, not the end: only a null cursor ends it.
Rich text
Texts such as a lesson’s body or a product’s description come back as HTML in a closed format, wrapped in <rich-text version="1">: paragraphs, headings, lists, tables, quotes, code, links and a few marks, with images, videos, audio, slideshows, formulas, diagrams, maps and downloads as <block type="…" props="{…}"></block> elements. A client can show it as it is, or read the text out of it.
Writes
Writes carry no idempotency key: a write that failed may still have landed. Read the state back before trying again, for instance with get_subscription after a cancel_subscription that timed out.
Errors
A call can fail in two ways: the tool refuses it, which comes back as a tool result, or the request itself is refused, which comes back as an HTTP status.
Tool errors
A tool that refuses answers a result with isError: true, a sentence for the model in content, and the details in structuredContent:
{
"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
}codesays what went wrong, from the list below (aclient-fault, at the end, hastypeinstead).contextsays where: the argument’spathand thereasonforinvalid, thekindandrefof what wasn’t found, thereasona call isn’t permitted, and so on.retry_after, when present, is how many seconds to wait before trying again.transient: true, on a read that failed on Sherpo’s side or couldn’t reach it (internalorunavailable), means trying the same call again may work.
| Code | What it means | What to do |
|---|---|---|
invalid |
An argument is malformed; context.path and context.reason say which and why. |
Fix the argument. |
not_found |
Nothing matches the reference given. | Check the id or slug, for instance with a list. |
not_entitled |
The customer may not open this: it’s locked, or the store keeps it off MCP. | Tell the customer what it needs (requires on the product or lesson says), or use the store’s site. |
not_permitted |
This caller may not make this call; context.reason says why: limit (too many calls, with retry_after), principal (for instance an unverified app resuming a subscription), plan (the store’s plan doesn’t include it) or paused (new unlocks are paused for now). |
Wait for retry_after, or send the customer to the store’s site. |
conflict |
The call clashes with the current state, such as a body still uploading (context.field is status). |
Read the state again; retry a pending one shortly. |
internal |
The call failed on Sherpo’s side. | Retry a read marked transient; read the state back after a write. |
unavailable |
The service couldn’t be reached. | Retry shortly. |
A result whose structuredContent has type: "client-fault" failed in the server’s own handling of the call; don’t retry it unchanged.
HTTP answers
| Status | When | What to do |
|---|---|---|
401 |
No token, or one that expired or was revoked. WWW-Authenticate names resource_metadata. |
Refresh the token, or sign the customer in again (see Sign-in). |
403 |
The token lacks a scope the call needs: WWW-Authenticate reads Bearer error="insufficient_scope". |
Ask the customer to connect again with that access. |
429 |
Too many refused tokens came from your network for this store; Retry-After says when to try again. |
Stop sending the refused token and wait. |
503 |
The store isn’t available for now; Retry-After says when to ask again. |
Wait and try again. |
413, 400 |
The body is too large, isn’t JSON, or is a batch. | Fix the request. |
A call naming a tool that doesn’t exist, or whose arguments aren’t an object, is a JSON-RPC error (-32602, invalid params) rather than a tool result.
Examples has a tool error, a 401 and a 403 with their full requests and answers.