Advanced catalogue

execute_read

read

Execute API read operation

Copy page

Read anything the partner API exposes, including the parts no curated tool covers, without being able to change any of it.

Overview

Runs one read-only Sign Customiser API operation, named by the stable operation id search_operations returns, with typed path, query and body arguments. It reaches every GET operation and every validate-only operation, and nothing else: an operation that writes is refused with the tool that does run it. Results are paginated exactly as the underlying operation paginates and are truncated with an explicit flag rather than silently. It requires the mcp:advanced scope plus the read scope the operation itself declares, which the result reports.

Permission

Needs no permission beyond a connected store.

Only visible to a connection grantedmcp:advanced. See theadvanced catalogue guide.

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

An operation id from search_operations.
A merchant has connected this store and approved mcp:advanced plus the read scope that operation requires.

Arguments

operation_idstringrequired

The stable id of the operation to run, from search_operations. It is the only way to name an operation: this tool accepts no URL, no path and no HTTP method.

pathobject

The operation path parameters, by name, exactly as search_operations lists them under parameters.path. An identifier the operation does not address is refused.

queryobject

The query parameters, by name, as search_operations lists them under parameters.query. Only read operations take any; a nested object such as filter is sent as the API expects it.

bodyobject

The JSON request body, matching the operation request_schema from search_operations. It is passed to the API unchanged, so a member the operation does not accept comes back as unknown_field naming its pointer. A GET or a DELETE operation takes no body and refuses one.

Result

The operation own response body, unchanged, with its pagination block where it paginates and a truncated flag when a large collection was trimmed to fit.

request_idstringalways present

The API request id, for support.

storeobjectalways present

The Store this connection resolved to.

store.idinteger

store.namestring

operation_idstringalways present

The operation that ran.

statusintegeralways present

The HTTP status the operation answered with.

dataobject

The operation own response data, unchanged. A collection operation returns a list.

paginationobject

Present when the operation paginates. Pass next_cursor back as query.cursor for the next page.

pagination.has_moreboolean

pagination.next_cursorstring

truncatedbooleanalways present

True when the result was too large to return whole and members were dropped from the end. The members returned are still a valid prefix.

Error cases

insufficient_scope

The connection holds mcp:advanced but not the read scope this operation needs. The error names it in required_scopes.

invalid_parameter

A path identifier of the wrong type; the error names which one and what it expects.

resource_not_found

The identifier does not exist in this store. Re-read the parent collection to find a valid one.

unknown_field

A path parameter the operation does not address, or a query object sent to an operation that takes none.

unsupported_value

Either no operation has that id, or it mutates. The error names the executor that owns it; call search_operations to confirm the id.

Read a font tier no curated tool covers

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_read",
    "arguments": {
      "operation_id": "listFontTiers",
      "path": {
        "customiser_id": 42
      },
      "query": {
        "limit": 2
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "operation_id": "listFontTiers",
      "status": 200,
      "data": [
        {
          "object": "font_tier",
          "id": 3,
          "name": "Premium",
          "price_multiplier": 1.25
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      },
      "truncated": false
    }
  }
}

A write is refused, and named (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_read",
    "arguments": {
      "operation_id": "deleteCustomiser",
      "path": {
        "customiser_id": 42
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "unsupported_value",
        "title": "Operation belongs to another tool",
        "detail": "The operation deleteCustomiser is a delete operation, which execute_read does not run. Call execute_delete instead.",
        "recovery": "Send one of the values in allowed_values for the field named by pointer or parameter.",
        "parameter": "operation_id",
        "allowed_values": [
          "execute_delete"
        ],
        "owning_tool": "execute_delete"
      }
    }
  }
}