MCP tool reference
Tools to inspect, deploy, run, and organize the backend for a connected store.
Tools automatically use the authorized store. They do not accept an arbitrary store ID. Tool names retain function; the merchant interface calls these works. A work is a draft, published or paused, and has one current version. Draft things run the newest version; published things run the current version.
Inspect the store and works
| Tool | Arguments | Result |
|---|---|---|
get_context | {} | Store, scopes, the publishing model, programming guide, limits, and an illustrative example. Call first. |
list_functions | { name?, prefix?, feature?, status?, limit?, after? } | Work summaries sorted by title: status (draft, published or paused), currentVersion (used to delete the work), newestVersion when a newer version is pending, previewUrl for HTTP works and, once published or paused, url, and recent protection notices. 50 per page by default (maximum 100); pass nextCursor as after. |
get_usage | {} | Compact current usage: remaining allowances, responses served from cache (cache, which don’t use runs), UTC reset dates, the most active existing works, one deletedWorks aggregate for works deleted since they ran, protection notices, and the store’s Usage link. Test runs count like any run. storage.collections.used counts the same entries as list_collections. Read-only. |
get_function | { name, version?, limit?, after? } | Status, currentVersion, newestVersion, URLs for HTTP works, and saved versions newest first, each marked current or not (10 per page by default, maximum 50; pass nextCursor as after), plus the manifest and source of one version: the one requested, or the newest. |
Deploy, test and publish
| Tool | Arguments | Effect |
|---|---|---|
deploy_function | { manifest, source } | Validates code and saves a new immutable version. On a new or draft work it becomes current; on a published or paused work it is pending until published. Returns the version, whether it is current, the status, previewUrl for HTTP works and url once published. |
invoke_function | { name, version?, input, idempotencyKey, trigger? } | Runs a work and returns its result, runId, test and the version run. Without a version, a published work runs its current version for real and a draft its newest version as a test; a paused work needs a version. Any other version is a test run. Page works always run as tests here. The key is required and must be 1–128 characters. For event and schedule works, trigger: {event: {topic, payload?}} or {schedule: {scheduledFor?}} builds the input as a real delivery would, as a test run; see automations. |
publish_function | { name, version? } | Makes a version (default: the newest) current and the work published, so it serves real traffic. Publishing an earlier version is a rollback; publishing a paused work also resumes it. Returns the version and the previous version and status. |
set_function_state | { name, paused } | Pauses or resumes a published work. The current version is kept. Drafts cannot be paused. |
delete_function | { name, version } | Stops and deletes a work at its current version in one call; retains data and history. |
purge_cache | { name } | Clears every cached response of a public GET work that declares trigger.cache; the next request for each query runs it again. Takes effect within about 15 seconds and returns { work, effectiveBy }. See Cache a public read. |
delete_test_records | { feature? } | Deletes every document created by a test run and not since updated by a real run, in the store or one feature, and returns how many were deleted. Shopify and external effects are not reversed. |
delete_record | { feature, collection, id, revision } | Deletes one real or test record at the revision shown by read_collection and returns whether it was a test record. Fails with WRITE_CONFLICT for a stale revision and DOCUMENT_NOT_FOUND for a missing record. |
delete_function requires the work’s current version and fails with FUNCTION_CHANGED if another version was published since you read it. It also fails with VIEW_WORK_IN_USE while a draft or published page names the work. The work does not need to be paused first: deletion stops it and removes the work registration and endpoints while retaining records and execution/version history. Version history belongs to the work’s name, so a new work deployed under the same name continues its version numbers. Deletion does not undo Shopify or external effects.
Test runs use the store’s real documents, secrets, Shopify store and external services. Only documents they create are test records; updates and deletes of existing documents are real. Publishing or rolling back changes which code runs; it does not undo earlier side effects or restore records.
Inspect data and runs
| Tool | Arguments | Result |
|---|---|---|
list_collections | { feature? } | One entry per feature and collection, with record counts, test record counts (testCount) and uniqueness rules, including configured collections without active records. get_usage counts these same entries. |
read_collection | { feature, collection, limit?, after? } | A page of records (20 by default, maximum 50), each with test: true when a test run created it. Pass nextCursor as after for the next page. |
list_runs | { name?, outcome?, test?, limit?, after? } | Executions newest first with outcome, test, version, response status and timing. outcome is running, succeeded, returned_error (the work returned an HTTP 4xx/5xx response) or failed; filter by one of those or attention (returned_error or failed), and by test. 20 per page by default (maximum 100); pass nextCursor as after. Inputs and outputs are not retained. |
get_run | { runId } | Whether it was a test run, the exact version and its source, outcome, response status, bounded logs, and redacted error details. |
list_events | { work?, status?, limit?, after? } | Recent Shopify events for event works, newest first, and what each did for each work: ran (with runIds), skipped (its when didn't match), paused, pending or retrying (with nextAttemptAt), failed or expired. Events are kept for seven days; payloads are not returned. |
list_jobs | { work?, status?, key?, limit?, after? } | Background jobs newest first: status (held, queued, retrying, succeeded, failed, canceled or expired), running, runAt, attempt and maxAttempts, runIds, errorCode, enqueuedBy, chain (rootId, generation), test and inputBytes. Inputs are not returned. Finished jobs are kept for seven days. |
cancel_jobs | { work, id?, key?, status? } | Cancels a work's queued or retrying jobs: one by id or key, those with one status, or all of them. Running jobs finish. |
retry_job | { id } | Queues a failed or expired job again with a fresh set of attempts, the same key and input. |
Manage merchant views
| Tool | Arguments | Result |
|---|---|---|
list_views | {} | Merchant views and their draft/published pointers. |
get_view | { name, stage? } | Draft or published definition and current version pointers. |
save_view | { definition, baseVersion, validateOnly? } | Validates the definition and the works it names, saves a draft (unless validateOnly) and runs each data work once as a test run. Returns the version, manageUrl, and checks on what the works returned: missing fields, values that don't fit their kind, unresolvable Shopify IDs, empty tabs. Issues carry a code, path and message. Use null baseVersion for a new page. |
suggest_view | { work } | Runs a data work once as a test run and returns a draft definition, with each field's kind and a pattern inferred from the result. |
unpublish_view | { name, version, publishedVersion } | Frees a published slot while keeping the draft, works and data as they are. |
publish_view | { name, version, publishedVersion, workVersions? } | Publishes the draft and, together, every work it uses whose newest version is not current. Returns publishedWorks. Fails with VIEW_WORK_PAUSED while a work it uses is paused. With workVersions (the version of each work you tested on the draft page), fails with WORKS_CHANGED and publishes nothing if a work has a newer version. |
delete_view | { name, version, publishedVersion } | Removes the view. Preserves works, documents, and saved definitions. |
See Build a merchant page for field kinds, patterns, the data work contract and a complete example. Merchants run page actions inside Shopify; agents test page works with invoke_function, which always makes test runs for them.
Handle tool errors
Failed tool calls return isError: true and a JSON error object containing a code and message. Invocation errors include runId once execution has started. Use it with get_run. Validation and admission failures before execution do not create a run.
Use delete_function with the work’s current version; it stops and deletes the work in one call. Merchants can also delete it from its detail page. Stored data, versions, and run history remain. See Manage works.
Connection details
The endpoint is https://littleworks.app/mcp, served over Streamable HTTP. OAuth uses mandatory S256 PKCE, exact registered callbacks, and resource-bound tokens. Dynamic client registration is supported; URL-based client metadata documents are not currently supported.
Access tokens last one hour; refresh tokens rotate. Grants expire after 90 days. Disconnecting invalidates that grant’s tokens immediately. Clients should use their supported OAuth flow rather than asking the merchant to handle tokens manually.