The server at https://mcp.sherpo.io offers 284 tools in all. A connection sees only the ones it may call, and every tool has its own page under Tools with its arguments, its answer and its errors.
What the server says first
When a client connects, the server sends these instructions, followed by a summary of the rich text format:
Sherpo's merchant tools act on the stores this connection reaches, which
list_merchantslists with their businesses. A store tool takesstorewhen the connection reaches more than one, and acts on that store's business. Most writes carry no idempotency key: after a failed write, read the state back before trying again.record_ordertakessource_keyandrecord_portfolio_eventtakesidempotency_key. Send an order's samesource_keyon every resend: aconflictatsource_keythen means the first call landed, andcurrentnames its order, even when the resend's customer, currency or lines changed since; when they did, read that order back withget_orderto check it is the same sale. Send an event's sameidempotency_keywith the same arguments: the event recorded comes back. The key is its portfolio's own, and on that portfolio other arguments are aconflictatevent, andcurrentnames the event recorded. A private file comes back insideget_asset_url's result, never through itsurl.
The server offers tools only: no prompts and no resources.
Listing tools
tools/list answers the tools this connection may call, read from its scopes, not every tool the server has. A connection holding only the Catalog set lists only the tools its scopes allow. The list follows the connection’s current access.
Tools come 50 to a page, with a nextCursor while more follow. MCP clients page through it on their own.
Each tool carries:
name: snake case, such aslist_products.title: a short title, such as “List products”.description: what it does, the scope it needs and, for a list, its paging, filters, sorts and search.inputSchemaandoutputSchema: JSON Schema of its arguments and its answer.annotations:readOnlyHintis true for reads.idempotentHintis true for reads only: even the two writes that take a key of their own repeat without it (see Writes and retries). A write hasdestructiveHintfalse when it only adds, such ascreate_product, and true when it may change or remove what is there.openWorldHintis always false.get_asset_urlis marked a write, withdestructiveHintfalse, since it hands out a link and records a download as a delivery; nothing else changes.
Picking a store
A connection reaches one or more stores, of one business or, for a connection the seller picked several businesses for, of each of them. The store picks the business a call acts on. Every tool that acts on a store takes a store argument, the id of the store to act on, listed in its schema as one of the connection’s stores.
- With one store,
storemay be left out: the call acts on that store. - With more than one,
storeis required.
A missing or wrong store is a tool error, and the connection stays as it is:
- Left out while the connection reaches more than one store:
invalidwithcontext: { "path": ["store"], "reason": "required" }. - A store the connection was never approved for:
invalidwithcontext: { "path": ["store"], "reason": "not a store of this connection" }. - A store of a business the connection no longer reaches, such as one the seller removed it from:
not_permittedwithcontext.reasonset toprincipal.
Two account tools act on the business instead of a store and take no store to act on: list_merchants and get_merchant. Passing one to get_merchant is invalid with the reason “not taken by this tool”. list_merchants takes a store of its own, as an object { "id": "..." }, which narrows the list to the business holding that store.
References
An argument naming a record is an object, never a bare string: { "id": "..." }. Some tools also take a product by its slug, as { "slug": "..." }. The exception is the store a store tool takes, a plain string id (see Picking a store).
{ "order": { "id": "5f0c8d2e-41a7-4b9e-9c3d-2a6f1e8b7c40" } }A reference that matches nothing is not_found.
Lists and paging
A list tool takes one query object, every field optional:
filter: per field, with the operators each field takes, such aseq,in(up to 50 values),gteandlte. A bare value meanseq.sort:{ "name": "...", "direction": "asc" }or"desc".search: text to search for, up to 200 characters.limit: how many items a page holds.cursor: thecursorof the page before, for the next one.count: true to also answer thetotal.facets: fields to answer counts by, for the lists that offer them.
{
"query": {
"filter": { "status": { "in": ["draft", "scheduled"] }, "category": "course" },
"sort": { "name": "created", "direction": "desc" },
"limit": 50,
"count": true
}
}The answer holds items and cursor, plus total and facets when asked. Pass cursor back for the next page; it is null on the last one.
A page holds 20 items unless limit says otherwise, on most lists. Each tool’s page says its own most, 100 for most lists and up to 1,000 for a few. Each tool’s description also lists the fields it filters, sorts and searches.
Search follows two rules:
- An empty page with a cursor means nothing so far: only a null cursor ends a search.
- A searched page past the count budget comes back without its total and facets, which never means zero.
Where a search covers id, an id matches only when typed whole.
Answers
A successful call answers its result in structuredContent, and the same JSON as text in content, so a client reading only text sees what the output schema describes. An answer that isn’t an object, such as the list list_integrations answers, is wrapped under result:
{
"content": [{ "type": "text", "text": "{\"result\":[]}" }],
"structuredContent": { "result": [] }
}A write that takes a long text or binds files answers short, so a call doesn’t pay again for what it sent. set_body, edit_body and publish_body answer the attachment, the asset the body holds now (the from of the next write) and the attachments they created, with the preview link a set or an edit answers and the blocks an edit touched. The writes of products, entries, pages and quizzes answer the record without its long texts, attachments and files, with the attachments its texts created. Pass full: true to have those answered too, as the matching read answers them.
A refused call is a tool error with isError: true. See Errors.
Rich text
Rich text fields, such as a product’s description or an entry’s teaser, take HTML in a closed format:
- Text:
p,h1(Title),h2(Heading),h3(Subheading),br, marks, links, colored spans and text alignment. - Structure: lists and task lists, tables, code blocks,
blockquote,hr,detailswithsummary, andfigurewithfigcaption. - Images, videos, audio, slideshows, formulas, diagrams, maps, downloads and other blocks are
<block type="..." props="{...}"></block>elements. There is no rawimg,videooriframe.get_body_schemaanswers each block’s props and the values they take, and a prop it doesn’t list is refused.
Anything else is refused as invalid, with context.path naming the field and context.reason what is wrong. The server’s instructions and each writing tool’s description carry the exact list.
<h1>Welcome</h1><p style="text-align: center">Start with <strong>the intro</strong>, then <a href="https://example.com/notes" target="_blank">read the notes</a>.</p>A read answers the stored form, wrapped in <rich-text version="1">. Send it back as it is to keep a text unchanged.
To write Markdown instead, pass text_format: "markdown" with the write. Every rich text field of the call is converted from Markdown (CommonMark with tables, task lists and strikethrough), then checked the same way. A $$ fence (or a paragraph that is one $$ ... $$ line) becomes a formula block, while a $$ nothing closes stays text. A mermaid code fence becomes a diagram block, unless the diagram’s rules refuse it, when it stays a code block; one that passes them but still can’t be drawn is refused, as is a save holding more than 10 new diagrams. A Markdown image is refused, since an image is a block.
A text holds at most 1 MiB of UTF-8, within its field’s own limit, and a text sent as Markdown at most 64 KiB.
A body’s target names whose it is by its kind and id. The store’s home is { "kind": "store" }, with the store’s id as id or none.
A body’s blocks each carry an id, which read_body answers and which stays the same across writes. To change a few blocks, edit_body takes edits (update, insert, move or delete a block by its id), applied in order and landing together, instead of sending the whole body to set_body. It checks the result as set_body does, and refuses an edit over a body that changed since from was read with a conflict whose context.path and context.reason name the argument and what it takes: read the body again and redo the edits. from and live take the body’s asset.id, never its attachment.id.
Writes and retries
Most writes take no idempotency key. Two take one of their own in their arguments:
record_ordertakessource_key, your own id for the sale. Only when you sent asource_keyis a retry safe: send the same one again. Aconflictwith{ "field": "source_key", "current": "<order id>" }means the first call landed, andcurrentnames its order. The key is checked before the order’s fields, so the conflict comes back even when the customer, the currency or a line changed since. When the resend’s arguments differ from the first call’s, read the ordercurrentnames withget_orderto check it is the same sale.record_portfolio_eventtakesidempotency_key, your own key for the event. A retry with the same key and the same arguments answers the event already recorded. The key belongs to the portfolio: the same key on the same portfolio with different arguments is aconflictwith{ "field": "event", "current": "<event id>" }, and on another portfolio it records a new event.
Without a key, when a write fails or its answer is lost, read the state back before trying again, so the write doesn’t land twice.
Bulk
bulk runs one tool on up to 50 items in a call. It takes:
accessor: which tool to run, by the name in the first column below (camelCase, not the tool’s name).items: each item’s arguments, as the tool alone takes them.
{
"accessor": "unpublishProduct",
"items": [
{ "product": { "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80" } },
{ "product": { "slug": "spring-workshop" } }
]
}Each item needs the scope of the tool it runs. bulk is listed while the connection holds the scope of any of them.
The answer is results, one per item in order: { "outcome": "done" }, or { "outcome": "refused", "error": { "code": "...", "detail": { ... } } }. A refused item doesn’t fail the call: the call succeeds, and its first text says how many were refused, as in “1 of 2 items refused.”.
accessor |
Runs |
|---|---|
publishProduct |
publish_product |
unpublishProduct |
unpublish_product |
discontinueProduct |
discontinue_product |
reinstateProduct |
reinstate_product |
unlistProduct |
unlist_product |
relistProduct |
relist_product |
deleteProduct |
delete_product |
publishEntry |
publish_entry |
unpublishEntry |
unpublish_entry |
deleteEntry |
delete_entry |
publishPage |
publish_page |
unpublishPage |
unpublish_page |
deletePage |
delete_page |
deleteAsset |
delete_asset |
archiveDiscount |
archive_discount |
restoreDiscount |
restore_discount |
deleteDiscount |
delete_discount |
disableLicense |
disable_license |
enableLicense |
enable_license |
recordLicense |
record_license |
hideReview |
hide_review |
unhideReview |
unhide_review |
Uploading files
A file is uploaded one of two ways:
- In the call, for a file up to 2 MiB:
create_inline_uploadtakes whatcreate_uploadtakes, with the file’s bytes asdatain place of its size inbytes, and answers the file, alreadyready. It needs no request outside MCP, so it works for a client that can’t reach the internet on its own. - Through an upload URL, for a larger file or a client that can send its own HTTP requests: three steps, below. The bytes never pass through the MCP server.
data is base64 as in bytes in arguments. Past 2 MiB it is invalid; a call past the request body limit in limits is refused before it reaches the store.
Through an upload URL:
Call
create_uploadwith the file’sname,mime, size inbytesand, optionally, itsenforcement. It reserves the file and answers it asasset, withupload: theurlto send the bytes to, themethod(PUT), theheadersto send andexpires_at.Send the bytes to
upload.urlwith aPUTand every header inupload.headers, within 15 minutes. This is a plain HTTP request, so the client needs to make one outside MCP. Any other header it sends is dropped when the upload completes.Call
complete_uploadwith theasset. To give up instead, callcancel_upload.
A file is up to 5,115 MiB through an upload URL. enforcement decides, either way, who may reach its bytes:
signed, the default: served only through links that expire, the one for anything you sell. It takes any media type.public: anyone with its link may load it, such as images on your pages. It takes only images (not SVG), video, audio and PDFs.
move_asset with the other enforcement changes it later.
To swap a file’s bytes and keep where it is used, upload the new bytes either way, then call replace_asset with the file as asset and the new one as upload. A link to a file hosted elsewhere, such as an external video, is made with create_asset instead.
Neither create_upload nor create_inline_upload takes a key: after a failure, look for the file with list_assets before trying again.
Bytes in arguments
A small image, such as the store’s icon in set_store_icon or the business’s logo in set_organization_logo, goes in the arguments themselves, as does a small file’s data in create_inline_upload, as base64: the standard alphabet with padding, no line breaks and no data: prefix. Anything else is invalid.
Reading files
get_asset_url takes the file as asset and, optionally, disposition: inline to view it, or attachment to download it.
- A file anyone may open, a link or a public file viewed inline, comes back as its
url. - Anything else, a private file or a download asked for as an attachment, comes back inside the result. Sherpo fetches the file and adds it to
contentas an embedded resource, with theuriurn:sherpo:asset:<id>, itsmimeType, and the file astextfor a text file or as base64 inblobotherwise. Read the file from there: the answer’surlserves no one.
{
"type": "resource",
"resource": {
"uri": "urn:sherpo:asset:3c9a1f60-7b2d-4e85-a0c4-6d8e2f1b9a73",
"mimeType": "text/csv; charset=utf-8",
"text": "email,product\nada@example.com,Spring workshop\n"
}
}A file handed back this way is up to 8 MiB. A larger one is a tool error, invalid: “The file is larger than 8 MiB, past what a tool result carries.”