MCP troubleshooting

Use MCP results and the customer's current connection state to diagnose a failure. Returned messages can be translated; avoid matching exact English message text in client logic.

Connection and authorization

Symptom	What to check
`401` or `invalid_token`	The access token may be missing, expired, revoked, or issued for another resource. Refresh the connection or repeat customer authorization when needed.
`403` or `insufficient_scope`	Check the granted scopes and discover tools again. New permissions require customer authorization.
A tool is missing from `tools/list`	Tools are filtered by granted scopes. Checkout tools also depend on the server's spending policy.
`invalid_client`	Verify the client ID, callback registration, and CIMD availability. For CIMD, the HTTPS JSON document must be reachable directly and contain a matching `client_id`.
`invalid_scope`	Request supported scopes from the current server metadata rather than copying a scope list from another environment.
`invalid_grant` during exchange or refresh	Check the client, resource, callback, PKCE verifier, expiry, and current refresh token. If authorization cannot be recovered, reconnect the customer.
`405` on the MCP URL	The endpoint accepts `POST`. A browser `GET` or legacy SSE connection is not supported by this transport.
`404` on the connector	Verify the endpoint and environment. The production MCP endpoint is https://api.chowdeck.com/mcp.
`429`	Stop immediate retries and back off. Respect any returned retry timing.

Addresses, menus, and carts

An address must belong to the connected customer. If a saved address is unavailable, list the customer's addresses again rather than guessing an ID. Resolve a new address before asking the customer to approve saving it.

Use current restaurant menus for item and modifier IDs. If an item becomes unavailable or the cart changes, fetch the latest menu and cart, ask for any needed selection, and prepare checkout again.

Vouchers

Symptom	Next action
Discovery returns no offers	Check currency and any vendor filter. The customer may already have claimed the available offers; check `get_voucher_balances`.
A previously claimed code is absent from discovery	This is expected. Discovery excludes vouchers already claimed by the customer.
A claim fails	Slots, expiry, phone eligibility, active-balance limits, or failed-attempt limits may prevent claiming. Follow the returned result and do not keep retrying.
A security answer is required	Ask the customer for the answer. Never infer or brute-force it.
A claim response is uncertain	Check `get_voucher_balances` before retrying.
A voucher cannot be applied	Check the balance, expiry, currency, vendor restrictions, and checkout quote. A claim alone does not guarantee eligibility for every order.

Checkout and payment

Preparation and confirmation are separate steps. A successful preparation provides a quote and an expiring confirmation token; it does not place an order.

Symptom	Next action
Payment option unavailable	Fetch eligible payment options for the currency and amount, then let the customer choose. Card checkout requires a returned card ID.
Insufficient wallet funds	Present the returned shortfall and ask the customer to fund the wallet or choose an eligible saved card.
Spending limit reached	Explain the restriction. Do not bypass it by splitting or duplicating orders.
Quote changed or confirmation expired	Prepare checkout again, show the current quote, and obtain fresh approval.
Confirmation already used	Check the known order's status. Replays are rejected; they do not reliably return the original success result.
Payment pending	Use `get_checkout_status` for the order and report the returned state. Avoid placing a replacement order automatically.
Confirmation times out	Preserve the attempt and any known order ID. Reconcile the result before starting another checkout; a timeout is not proof that no order was created.
Service temporarily unavailable	Back off and report the interruption. For a payment or confirmation attempt, establish the outcome before retrying an action that could create another order.

If an outcome remains unclear, retain the order reference and the time of the attempt for support. Exclude access tokens, refresh tokens, checkout credentials, security answers, and delivery PINs from diagnostic logs shared with others.