> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Tool Reference

> Every tool the MCP server offers, what it is for and which permission it needs.

58 tools ship with the server. An assistant is only ever shown the ones you approved, so a connection for products alone sees roughly a dozen.

The catalog is deliberately not a mirror of the API's 500-odd operations — a tool list that size makes a model worse at choosing, not better. Tools cover the operations a merchant asks for by name; everything else is reached through the three generic ones under [store setup](#store-setup).

<Note>
  The **Permission** column is what you have to approve for the tool to be offered. A dash means it has no permission of its own and is checked per record instead: `search_resources` is offered to everyone, but only finds what you approved.

  The last column says whether the tool reads or writes. A write asks your client to confirm before it runs.
</Note>

### Finding and reading

| Tool | Permission | |
| - | - | - |
| `describe_resource` | — | read |
| `search_resources` | — | read |
| `get_resource` | — | read |

### Reporting

| Tool | Permission | |
| - | - | - |
| `describe_reporting` | `read_reports` | read |
| `query_report` | `read_reports` | read |

### Catalog

| Tool | Permission | |
| - | - | - |
| `products_activate` | `write_products` | write |
| `products_draft` | `write_products` | write |
| `products_archive` | `write_products` | write |
| `products_approve` | `write_products` | write |
| `products_reject` | `write_products` | write |
| `variants_create` | `write_products` | write |
| `variants_update` | `write_products` | write |
| `catalogs_activate` | `write_products` | write |
| `catalogs_deactivate` | `write_products` | write |
| `price_lists_activate` | `write_products` | write |
| `price_lists_deactivate` | `write_products` | write |
| `curate_products` | — | write |

### Orders and payments

| Tool | Permission | |
| - | - | - |
| `orders_cancel` | `write_orders` | write |
| `orders_complete` | `write_orders` | write |
| `payments_capture` | `write_payments` | write |
| `payments_void` | `write_payments` | write |
| `refunds_create` | `write_refunds` | write |

### Fulfilment

| Tool | Permission | |
| - | - | - |
| `fulfillments_create` | `write_fulfillments` | write |
| `fulfillments_mark_delivered` | `write_fulfillments` | write |
| `deliveries_update_tracking` | `write_orders` | write |
| `shipping_labels_purchase` | `write_orders` | write |
| `shipping_labels_refund` | `write_orders` | write |

### Stock and purchasing

| Tool | Permission | |
| - | - | - |
| `set_stock` | `write_stock` | write |
| `stock_transfers_mark_draft` | `write_stock` | write |
| `stock_transfers_mark_ready` | `write_stock` | write |
| `stock_transfers_mark_in_transit` | `write_stock` | write |
| `stock_transfers_receive` | `write_stock` | write |
| `stock_transfers_cancel` | `write_stock` | write |
| `stock_transfers_close` | `write_stock` | write |
| `purchase_orders_mark_draft` | `write_purchasing` | write |
| `purchase_orders_mark_ordered` | `write_purchasing` | write |
| `purchase_orders_receive` | `write_purchasing` | write |
| `purchase_orders_cancel` | `write_purchasing` | write |
| `purchase_orders_close` | `write_purchasing` | write |

### Sellers

| Tool | Permission | |
| - | - | - |
| `sellers_invite` | `write_sellers` | write |
| `sellers_approve` | `write_sellers` | write |
| `sellers_reject` | `write_sellers` | write |
| `sellers_suspend` | `write_sellers` | write |
| `sellers_reopen_onboarding` | `write_sellers` | write |
| `seller_requirement_submissions_accept` | `write_sellers` | write |
| `seller_requirement_submissions_reject` | `write_sellers` | write |
| `seller_requirement_submissions_waive` | `write_sellers` | write |

### Files

| Tool | Permission | |
| - | - | - |
| `upload_file` | `write_products` | write |
| `media_create` | `write_media` | write |
| `create_import` | — | write |
| `propose_import_mapping` | — | write |
| `describe_import_mapping` | — | read |
| `get_import_status` | — | read |
| `create_export` | — | write |

### Creating, changing and deleting records

Three tools cover everything your store can write — 38 kinds of record, from
products and orders to markets, tax rates and delivery methods — rather than
one tool each. Creating an order through an assistant does exactly what
creating one in the dashboard does.

| Tool | Permission | |
| - | - | - |
| `create_resource` | — | write |
| `update_resource` | — | write |
| `delete_resource` | — | write |
| `tax_exemption_certificates_verify` | `write_customers` | write |

The dash is the point: each call is gated on the resource being written, so a
connection approved for products can create a product and is refused a market.
Call `describe_resource` for what a resource accepts.

## Resources

Beyond tools, the server offers MCP **resources** — files a client can fetch rather than operations it can run.

| Resource | What it is |
| - | - |
| `spree+export://<id>` | A finished export, as CSV. Reading one costs the same permission as reading the records in it, and an export of gift cards or coupon codes is never readable here. |

A product's media, an order's purchase order and an import's own file are things an assistant *puts* there rather than reads back, so they are uploads rather than files it can fetch.

## What no tool will do

Some things are out of reach whatever you approve.

* **Keys and codes.** API keys, integrations, webhooks and gift card codes are never shown. A gift card code is the money itself, and an integration's settings hold the passwords for another service.
* **Making another way in.** An assistant cannot create API keys, roles, staff accounts or register another assistant — so it can never widen its own reach.
* **Erasing a customer.** GDPR erasure is irreversible and is not something to put behind a single confirmation prompt. Do it in the dashboard.
* **Codes that spend money.** A gift card or coupon export carries live codes, so no tool creates or reads one. Download it from the dashboard.

25 further workflows are excluded for reasons a contract spec enforces, so one cannot be exposed by accident.

## Writing records

Two things worth knowing about the generic writes:

**Nested records travel with their parent.** A product's variants carry their own options, prices and stock levels in the same write, so creating a product with two sized variants is one call rather than four. `describe_resource` reports what fits inside each list.

**A list replaces rather than appends.** Sending one variant leaves a product with one variant. Send every row you want to keep.

## See also

<CardGroup cols={2}>
  <Card title="Permissions and consent" icon="shield-check" href="/docs/developer/mcp/permissions">
    What you approve, and what an assistant can never reach.
  </Card>

  <Card title="Custom tools" icon="puzzle-piece" href="/docs/developer/mcp/custom-tools">
    Add your own, or expose a workflow your extension ships.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.