Tool Guide

What FluentCart MCP exposes by default, what reversible mode adds, and what deliberately stays absent.

FluentCart MCP does three things:

finds the part of the store you are asking about;
describes the exact input before calling it;
reads the store, or performs an explicitly enabled reversible change.

The server discovers your store's REST routes at startup. A tool appears only when both the product policy and the connected WordPress principal allow it.

The source catalogue is not your tool list

The source contains reviewed definitions for FluentCart routes that the product deliberately refuses to execute. Your client's tools/list response is the authority for that connection. A definition in source does not make an operation available.

The default surface

Dynamic mode is the default. With writes disabled it presents three tools:

Tool	Purpose
`fluentcart_search_tools`	Find relevant reads by plain-English query and optional category
`fluentcart_describe_tools`	Return exact input schemas and annotations for selected reads
`fluentcart_execute_read_tool`	Validate and execute one discovered read

Set FLUENTCART_WRITE_MODE=reversible and one more tool appears:

Tool	Purpose
`fluentcart_execute_reversible_write`	Execute a reviewed create or update that has read-back and a supported undo

There is no destructive or real-money executor.

What you can read

The exact names depend on the routes your store serves, but the reviewed surface covers:

Area	Typical work
Orders	Orders, line items, transactions, addresses, activity and fulfilment state
Products	Catalogue, variants, pricing, stock, downloads, licences, taxonomy and bundles
Customers	Profiles, addresses, order history, subscriptions and lifetime-value context
Subscriptions & renewals	Billing relationships, individual renewal records, renewal state, transactions and upcoming payments
Reports	Revenue, trends, top products, customers, refunds, retention and attribution
Coupons	Coupon definitions, eligibility and usage
Shipping	Zones, methods, classes, packages and destination calculations
Tax	Classes, rates, EU VAT settings, records and overrides
Store configuration	Modules, roles, permissions, email, print templates and integrations
Reference data	Countries, currencies, payment methods, statuses, labels and categories

Search is the normal entry point. You do not need to memorise endpoint names:

Show me unpaid orders from the last seven days.
Which products are below their stock threshold?
What renews next week in PLN?

On FluentCart 1.6, the server can also list renewal records and open one renewal in detail. The subscription projection keeps the useful 1.6 context, including the collection method and pending skip state where the store returns them. It does not invent an outcome for an absent field.

Two field semantics worth knowing

In sales-report inputs, timezone is optional and echoed only as a label. FluentCart still filters dates in the store timezone, so supplying a different label does not change the figures.
In PDF seller-status output, e_invoice_profile is the configured ZUGFeRD/Factur-X profile; it is not a seller identity profile. The tool returns configuration status rather than private seller values.

What reversible mode adds

Reversible mode is for routine admin work that can be read back and restored or removed:

create or update products and variants;
create or update coupons and customers;
create or update shipping zones, methods and classes;
create or update tax classes, rates and shipping overrides;
create or update attribute groups and terms;
create or update order bumps and upgrade paths;
update product stock and taxonomy assignments;
update the reviewed tax settings document.
update only a subscription's total billing-cycle limit (bill_times) through a narrow, guarded path. It performs a best-effort preflight against fresh bill_times and bill_count, then verifies the result before it reports success. FluentCart 1.6 has no atomic version precondition; an ambiguous failure reports that the mutation may have applied and tells the caller to re-fetch instead of retrying blindly. 0 means unlimited billing cycles; a finite limit cannot move to or below the number of cycles already billed. Only store-billed manual or system subscriptions qualify; gateway-billed automatic subscriptions and subscriptions with linked FluentCart Pro licences fail closed before a write.

Subscription lifecycle endpoints remain out of scope. In FluentCart 1.6, pausing, resuming, or reactivating can change scheduled charges or related renewal state in ways the server cannot prove it can restore. The fact that an endpoint exists is not an undo button. Charges, renewal creation, skipping, voiding, resending, transaction synchronisation, refunds, and cancellation stay absent. The generic store-settings tool also rejects subscription_management_mode and subscription_system_charge; store-wide billing controls need their own dedicated guard.

Subscription gateway resync (fluentcart_subscription_fetch) is absent too. FluentCart 1.6 uses it to contact the gateway and can update local subscription state, which makes the old “read” label wrong. Use the FluentCart admin when a gateway resync is genuinely needed.

Create operations are not advertised as idempotent when FluentCart would create a duplicate on retry. Update operations are marked idempotent only when writing the same state twice has the same result.

Enable the mode explicitly:

{
  "env": {
    "FLUENTCART_WRITE_MODE": "reversible"
  }
}

What is not available

This server does not expose:

file uploads;
refunds or subscription cancellation;
deletion;
bulk mutations;
order-status changes or marking an order paid;
dispute handling or transaction-status changes;
role and permission changes;
plugin installation or integration credential changes;
emails, login actions or other external side effects.

No mode, environment variable or presentation style brings those actions back. Use FluentCart's admin or official operator tooling when you need them.

Presentation modes

All modes use the same filtered registry. Changing mode changes presentation, not authority.

Mode	What the client sees	Best for
`dynamic` (default)	Three read tools; four with reversible writes	Small context and broad discovery
`curated`	A reviewed shortlist registered directly	Common shop workflows with fewer discovery calls
`code`	Two read-only tools over an isolated JavaScript sandbox	Joining several reads before returning a concise result
`full`	Every definition this store and principal may use	Clients that prefer direct schemas and have room for them

Current measured counts and definition-token costs live in fluentcart-mcp/release-contract.json. They are generated from the built server rather than copied into this page.

Optional native FluentCart abilities

FluentCart supplies native WordPress Abilities for several advanced reads. The bridge is off by default and requires its own WordPress Application Password. The 2.1.0 evidence refresh audits the target runtime at FluentCart Core 1.6.0 and Pro 1.6.0:

FLUENTCART_ABILITIES_MODE=enabled
FLUENTCART_ABILITIES_USERNAME=ability-reader
FLUENTCART_ABILITIES_APP_PASSWORD=your-separate-application-password

It adds three read-only entry points:

Tool	Purpose
`fluentcart_search_abilities`	Search the audited reads discovered on this store
`fluentcart_describe_abilities`	Inspect the live input and output schema
`fluentcart_execute_read_ability`	Validate and execute one admitted read

Unknown abilities and all native writes remain absent. If the live catalogue or its read-only metadata drifts from the audited contract, startup fails closed.

Annotations

Tool annotations tell a client what it may safely do:

Annotation	Meaning
Read-only	The operation does not change store state
Idempotent	Repeating the same call has the same effect
Destructive	The operation removes or irreversibly overwrites data
Open-world	The operation creates data or reaches outside the current record

The server uses annotations together with its own risk registry. A friendly description never overrides policy.

Where the exact truth lives

release-contract.json — measured profiles, modes, counts, protocols and release evidence
manifest.json — packaged MCP metadata and advertised public tools
compatibility-support.json — captured FluentCart route and Ability evidence
your client's tools/list response — the actual surface for that store and principal

FluentCart 1.6+ compatibility

Version 2.1.0 is the FluentCart 1.6+ compatibility release: route discovery was refreshed and the nonfunctional legacy tax-country delete definition is absent. It represented an endpoint that could not execute, not a missing feature to restore.

The new renewal read surface is included. “1.6+” identifies the FluentCart family this work targets. The exact runtime verified for this release is WordPress 7.0.2 with FluentCart Core 1.6.0 and FluentCart Pro 1.6.0; it is not a blank cheque for a release that has not been tested yet.