Skip to content

Calling tools

How the merchant MCP server lists its tools, takes their arguments and answers them.

Updated

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_merchants lists with their businesses. A store tool takes store when 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_order takes source_key and record_portfolio_event takes idempotency_key. Send an order's same source_key on every resend: a conflict at source_key then means the first call landed, and current names its order, even when the resend's customer, currency or lines changed since; when they did, read that order back with get_order to check it is the same sale. Send an event's same idempotency_key with the same arguments: the event recorded comes back. The key is its portfolio's own, and on that portfolio other arguments are a conflict at event, and current names the event recorded. A private file comes back inside get_asset_url's result, never through its url.

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 as list_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.
  • inputSchema and outputSchema: JSON Schema of its arguments and its answer.
  • annotations: readOnlyHint is true for reads. idempotentHint is true for reads only: even the two writes that take a key of their own repeat without it (see Writes and retries). A write has destructiveHint false when it only adds, such as create_product, and true when it may change or remove what is there. openWorldHint is always false. get_asset_url is marked a write, with destructiveHint false, 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, store may be left out: the call acts on that store.
  • With more than one, store is 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: invalid with context: { "path": ["store"], "reason": "required" }.
  • A store the connection was never approved for: invalid with context: { "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_permitted with context.reason set to principal.

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 as eq, in (up to 50 values), gte and lte. A bare value means eq.
  • sort: { "name": "...", "direction": "asc" } or "desc".
  • search: text to search for, up to 200 characters.
  • limit: how many items a page holds.
  • cursor: the cursor of the page before, for the next one.
  • count: true to also answer the total.
  • 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, details with summary, and figure with figcaption.
  • Images, videos, audio, slideshows, formulas, diagrams, maps, downloads and other blocks are <block type="..." props="{...}"></block> elements. There is no raw img, video or iframe. get_body_schema answers 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_order takes source_key, your own id for the sale. Only when you sent a source_key is a retry safe: send the same one again. A conflict with { "field": "source_key", "current": "<order id>" } means the first call landed, and current names 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 order current names with get_order to check it is the same sale.
  • record_portfolio_event takes idempotency_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 a conflict with { "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_upload takes what create_upload takes, with the file’s bytes as data in place of its size in bytes, and answers the file, already ready. 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:

  1. Call create_upload with the file’s name, mime, size in bytes and, optionally, its enforcement. It reserves the file and answers it as asset, with upload: the url to send the bytes to, the method (PUT), the headers to send and expires_at.

  2. Send the bytes to upload.url with a PUT and every header in upload.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.

  3. Call complete_upload with the asset. To give up instead, call cancel_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 content as an embedded resource, with the uri urn:sherpo:asset:<id>, its mimeType, and the file as text for a text file or as base64 in blob otherwise. Read the file from there: the answer’s url serves 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.”

Type to search…

↑↓ navigate↵ selectEsc close