Prompt library

You are building a connector between a sales channel (a marketplace or a shopping cart platform) and Kentro, using the Kentro Channel API. Kentro is the system of record for orders, inventory and fulfillment. The connector moves the channel's products, customers and orders into Kentro and sends shipments, tracking and stock back to the channel.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages, and look up every endpoint and schema in them before you use it:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/reference/channel-api-getting-started.md
- https://docs.kentro.io/reference/channel-api-authentication.md
- https://docs.kentro.io/reference/channel-api-conventions.md
- https://docs.kentro.io/reference/channel-api-flows.md
- https://docs.kentro.io/docs/guide-sales-channel.md

Ask the user for these before writing code:
1. The channel platform, its API documentation and where its credentials are stored.
2. A Kentro sandbox API key pair, created in Kentro OS at https://kentro.cc under `Users` > `API keys`, with a permission group holding `channel:write` (or only the write scopes the connector needs) and bound to the target sales channel. Ask the user to store it in the environment variables KENTRO_KEY and KENTRO_SECRET. Never ask the user to paste a secret into the chat.
3. The Kentro sales channel id. If the user does not know it, call GET https://apis.kentro.dev/channel/v1/channels and ask the user to pick one.
4. Which system owns stock (the channel or Kentro), and which documents flow in each direction.

Rules:
- Build against https://apis.kentro.dev/channel/v1. Production is https://apis.kentro.live/channel/v1 with a production key, used only when the user asks.
- Call only the endpoints the Channel API reference documents. There is no Kentro SDK or CLI; use plain HTTPS.
- Send an Idempotency-Key on every write, derived from the channel's own ids (for example `<channel>-order-<id>-create`), and send the same key when you retry that write.
- Send externalId on every create, address documents as `ext:<channelId>:<externalId>`, and keep onDuplicate at update so a replayed feed never duplicates.
- Money is decimal strings in currency units ("12.50") with currency, and totals must add up. Order lines name the sellable variant, never the parent product.
- Retry only 429, 503, 500 and network errors, with backoff that honors Retry-After. Log requestId on every failure.

Steps:
1. Products: POST /v1/products with variants and the channel listing inline. When the channel owns stock, set it with PUT /v1/products/:id/inventory-levels.
2. Orders: POST /v1/orders with the customer inline, the lines, the totals and, when the channel collected payment, invoicing. Backfill history with X-Import-Mode: historical, and send large backfills to POST /v1/orders/import.
3. Fulfillment back to the channel: poll GET /v1/shipments?updatedSince=... and GET /v1/orders?updatedSince=..., walk every page to nextCursor null before advancing the watermark, and push tracking to the channel.
4. Cancellations and refunds: POST /v1/orders/:id/cancel, and refunds as the flows page describes.
5. Configuration for ids and keys (nothing hard-coded), scheduling and structured logs.

Acceptance checks. Run each one against the sandbox and show the user the requests and responses, with secrets redacted:
- GET /v1/channels answers 200 and includes the bound sales channel.
- One product POST answers 201 with outcome created; the same request again answers 200 with outcome updated or unchanged.
- One order POST with X-Dry-Run: true answers 2xx with the X-Dry-Run: applied header; the real POST then answers 201; repeating it with the same Idempotency-Key answers with Idempotent-Replayed: true.
- GET `/v1/orders/ext:<channelId>:<externalId>?include=items,customer` returns the order with the expected lines and totals.
- A shipment recorded for the order appears in GET /v1/shipments?orderId=..., and the connector pushes its tracking number to the channel.
- No secret appears in code, logs or the repository.

You are building a sync between Kentro and the user's ERP or accounting system, using the Kentro Channel API. It moves customers, invoices and payments in the directions the user chooses, and keeps both systems consistent without duplicates.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages, and look up every endpoint and schema in them before you use it:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/reference/channel-api-authentication.md
- https://docs.kentro.io/reference/channel-api-conventions.md
- https://docs.kentro.io/reference/channel-api-flows.md (sections "Invoice and pay separately" and "Keep in sync")
- https://docs.kentro.io/docs/guide-erp-accounting.md

Ask the user for these before writing code:
1. The ERP or accounting system, its API documentation and where its credentials are stored.
2. For each document type (customers, orders, invoices, payments), which system creates it and which system receives it.
3. A Kentro sandbox API key pair from Kentro OS at https://kentro.cc (`Users` > `API keys`) with only the scopes the sync needs: `channel:read` to read from Kentro, and `customers:write`, `invoices:write` and `payments:write` to write into Kentro. Ask the user to store it as KENTRO_KEY and KENTRO_SECRET in the environment, never in the chat.
4. The Kentro sales channel id the documents belong to (GET https://apis.kentro.dev/channel/v1/channels lists them) and the currency.
5. How the ERP's customer, invoice and payment ids map to Kentro externalId values.

Rules:
- Build against https://apis.kentro.dev/channel/v1 and call only the endpoints the Channel API reference documents. There is no Kentro SDK or CLI.
- Send an Idempotency-Key on every write, derived from the ERP document id and version, and reuse it on retries. Send externalId on every create and keep onDuplicate at update.
- Money is decimal strings in currency units with currency. Invoice and payment totals must add up (422 totals_mismatch otherwise). Use decimal arithmetic, never floats.
- Date-only fields such as dueDate take YYYY-MM-DD.
- When several ERP customers share an email address, send X-Customer-Match: externalId so they stay separate Kentro customers.
- A refund is an invoice of type refund plus a payment of type refund, both with positive amounts. A payment Kentro charged itself is refunded in the Kentro portal, not through the API (409 state_conflict with provider_refund_required): report those to the user instead of retrying.
- Retry only 429, 503, 500 and network errors, with backoff that honors Retry-After. Log requestId on every failure.

Steps:
1. Customers: POST /v1/customers as an upsert, or read Kentro's customers with GET /v1/customers?updatedSince=... when Kentro is the source.
2. Invoices: POST /v1/invoices with the order reference, lines, totals and dueDate, or export Kentro's invoices with GET /v1/invoices?updatedSince=....
3. Payments: POST /v1/payments with application.mode auto (oldest open invoices first) or manual with exact invoice amounts; POST /v1/payments/:id/apply applies one later.
4. Incremental export: one watermark per resource; follow nextCursor to null before advancing it.
5. A run report: documents created, updated, unchanged and failed, with the requestId of each failure.

Acceptance checks. Run each one against the sandbox and show the user the requests and responses, with secrets redacted:
- The same customer sent twice answers 201 created, then 200 updated or unchanged.
- An invoice whose totals add up answers 201; a copy with a wrong total answers 422 totals_mismatch, and the sync reports it without retrying.
- A payment with application.mode auto is applied to the open invoice; read it back with GET /v1/payments/:id.
- A write repeated with the same Idempotency-Key answers with Idempotent-Replayed: true.
- An export run picks up a document changed in Kentro since the last watermark, and a second run with no changes writes nothing.
- No secret appears in code, logs or the repository.

You are building an integration between a warehouse management system (WMS) or 3PL and Kentro, using the Kentro Channel API. Kentro routes orders into fulfillment orders. The integration hands those to the warehouse, reports what shipped with tracking, and keeps stock levels current.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages, and look up every endpoint and schema in them before you use it:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/reference/channel-api-authentication.md
- https://docs.kentro.io/reference/channel-api-conventions.md
- https://docs.kentro.io/reference/channel-api-flows.md (sections "Decide who fulfills", "Report what the warehouse shipped", "Record a shipment" and "Keep in sync")
- https://docs.kentro.io/docs/guide-warehouse-3pl.md

Ask the user for these before writing code:
1. The WMS or 3PL, its API documentation, and how it receives orders and reports shipments (API, webhooks or files).
2. The Kentro warehouse or warehouses the integration serves, and how the WMS names them.
3. A Kentro sandbox API key pair from Kentro OS at https://kentro.cc (`Users` > `API keys`) with `channel:read`, `fulfillment:write` and `shipments:write`, plus `products:write` when the warehouse reports stock. Ask the user to store it as KENTRO_KEY and KENTRO_SECRET in the environment, never in the chat.
4. Whether the warehouse reports stock, and how often.

Rules:
- Build against https://apis.kentro.dev/channel/v1 and call only the endpoints the Channel API reference documents. There is no Kentro SDK or CLI.
- Send an Idempotency-Key on every write, derived from the WMS's shipment or event id and reused on retries, so a retried shipment report never ships twice.
- Fulfill quantities are deltas, and a partial shipment leaves the fulfillment order open.
- Never ship a fulfillment order Kentro canceled: check its status before sending work to the floor and again before reporting.
- Retry only 429, 503, 500 and network errors, with backoff that honors Retry-After. Log requestId on every failure.

Steps:
1. Pull work: list the warehouse's fulfillment orders with GET /v1/fulfillment-orders, filtered by status, updatedSince and the warehouse filter the fulfillment orders list reference names, or read GET /v1/fulfillment-queue. Follow nextCursor to null.
2. Send each fulfillment order to the WMS with its lines and ship-to address.
3. Report shipments with POST /v1/fulfillment-orders/:id/fulfill: the shipped items and the tracking (carrier, number, url).
4. Stock: PUT /v1/products/:id/inventory-levels with warehouseId, onHand and a reason.
5. Changes: poll with updatedSince for cancellations and reroutes, and stop work Kentro canceled.

Acceptance checks. Run each one against the sandbox and show the user the requests and responses, with secrets redacted:
- The integration lists at least one open fulfillment order for the warehouse. If there is none, ask the user to create a test order in the sandbox.
- A partial fulfill answers 2xx and leaves the fulfillment order open; fulfilling the rest closes it.
- The same fulfill sent again with the same Idempotency-Key answers with Idempotent-Replayed: true and ships nothing twice.
- GET /v1/shipments?orderId=... lists the shipment with its tracking number, and the order's fulfillmentStatus reflects it.
- An inventory-levels PUT shows in the product's stock afterwards.
- No secret appears in code, logs or the repository.

You are building an integration that brings retailer purchase orders into Kentro through the Kentro Channel API, for purchase orders that arrive outside Kentro's own EDI connections (EDI files from a VAN, a retailer portal export, an email feed). Each purchase order is created in Kentro, then accepted, which turns it into a sales order Kentro routes and ships, or rejected.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages, and look up every endpoint and schema in them before you use it:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/reference/channel-api-authentication.md
- https://docs.kentro.io/reference/channel-api-conventions.md
- https://docs.kentro.io/reference/channel-api-flows.md (section "Retailer purchase orders")
- https://docs.kentro.io/docs/guide-retailer-edi.md

Ask the user for these before writing code:
1. Whether this retailer already reaches Kentro through a Kentro EDI connection. If it does, stop and tell the user: those purchase orders already arrive in Kentro, and a second path would duplicate them.
2. Where the purchase orders come from, and a few sample files (X12 850, CSV or JSON).
3. A Kentro sandbox API key pair from Kentro OS at https://kentro.cc (`Users` > `API keys`) with `purchase-orders:write`, plus `channel:read` to read the orders they become. Ask the user to store it as KENTRO_KEY and KENTRO_SECRET in the environment, never in the chat.
4. The retailer's sales channel in Kentro, the retailer's ship-to locations as customer externalId values, and how retailer item numbers map to Kentro SKUs.
5. The acceptance rules: which purchase orders to accept automatically, and which to hold or reject.

Rules:
- Build against https://apis.kentro.dev/channel/v1 and call only the endpoints the Channel API reference documents. There is no Kentro SDK or CLI.
- Create purchase orders with onDuplicate: error, so a purchase order received twice answers 409 duplicate. Record that answer as already received, not as a failure.
- Send an Idempotency-Key on every write, derived from the purchase order number and the action (po-4500262852-create, po-4500262852-accept).
- purchaseOrderDate, shipNotBefore and shipNotAfter take YYYY-MM-DD. Money is decimal strings with currency, and totals must add up.
- Lines name sellable variants by SKU. An unknown SKU answers 422 unresolved_reference: report it to the user, never guess a mapping.
- Retry only 429, 503, 500 and network errors, with backoff that honors Retry-After. Log requestId on every failure.

Steps:
1. Parse each purchase order into the POST /v1/purchase-orders body: channelId, externalId, purchaseOrderNumber, purchaseOrderDate, provider, customer, shipTo, items, totals and the ship window.
2. Create it, then call POST /v1/purchase-orders/:id/accept, or POST /v1/purchase-orders/:id/reject with a reason, following the user's rules.
3. After acceptance, follow the order with GET /v1/orders and GET /v1/shipments?orderId=... (with updatedSince) to produce what the retailer expects back, such as ship notices and invoices.
4. Log each purchase order's outcome with its Kentro ids.

Acceptance checks. Run each one against the sandbox and show the user the requests and responses, with secrets redacted:
- A sample purchase order answers 201 created; sending it again answers 409 duplicate, and the integration records it as already received.
- Accepting it answers 2xx, and the resulting order is readable with GET /v1/orders.
- A second sample purchase order is rejected with a reason and does not become an order.
- A purchase order with an unknown SKU answers 422 unresolved_reference and is reported to the user.
- No secret appears in code, logs or the repository.

You are building a custom storefront on the Kentro Store API. The user's own web application renders the pages, and its server calls the Store API for the buyer in front of it. Kentro keeps the catalog, prices, stock, buyer accounts, carts, quotes, checkout, orders and invoices. Use the framework the user names; default to Next.js with the App Router.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages, and look up every operation and schema in them before you use it:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/reference/store-api-getting-started.md
- https://docs.kentro.io/reference/store-api-authentication.md
- https://docs.kentro.io/reference/store-api-conventions.md
- https://docs.kentro.io/reference/store-api-flows.md
- https://docs.kentro.io/docs/guide-custom-storefront.md

Ask the user for these before writing code:
1. The framework and where the application will run.
2. The host of a published storefront in the sandbox (Kentro OS at https://kentro.cc, `Storefronts`). It is the X-Storefront-Host value.
3. A sandbox API key whose permission group holds `storefront:serve`, stored server-side as KENTRO_API_KEY. Never in the chat, never in client code.
4. Which pages to build first: catalog, product, cart, checkout, account or orders.

Rules:
- Call the Store API only from the server: Server Components, Route Handlers or Server Actions in Next.js, server routes in other frameworks. No Client Component, browser script or NEXT_PUBLIC_ variable ever holds the key or a token. The API sends no CORS headers for browsers.
- Base URL https://apis.kentro.dev/store/v1 while building (production https://apis.kentro.live/store/v1); buyer sign-in at https://apis.kentro.dev/auth. Every operation is POST `/<family>.<operation>` with a JSON body, `{}` when it takes no fields.
- Every call sends X-API-Key and X-Storefront-Host (from configuration, lower case, no scheme). Buyer calls add X-Storefront-Buyer and guest calls add X-Storefront-Guest. Also send X-Storefront-Client-Ip and X-Expected-Buyer. The API does not read Authorization.
- Keep buyer and guest tokens on the server, keyed by an httpOnly session cookie. Refresh on 401 with POST /auth/refresh.
- Money is integers in minor units; format it with the store's currency.
- Every cart mutation sends expectedRevision and ownershipVersion from the last cart answer. On 409 CONFLICT, read cart.get again and re-render.
- checkout.start sends idempotencyKey, quoteFingerprint and expectedRevision. Never start a second checkout while one is pending.
- Never cache Store API answers across requests. Call only the operations the Store API reference documents. There is no Kentro SDK: write a small server-only client module.

Steps:
1. A server-only Kentro client: one function that posts to an operation with the headers above and turns refusals (`{ code, message, fieldErrors }`) into typed errors.
2. store.get on each request; render according to access, publicPrices, guestCheckout, fulfillment and currency.
3. Catalog and product pages with the catalog operations on the flows page.
4. Buyers: sign in with POST https://apis.kentro.dev/auth/login/customer `{ email, password, host }`, sign out with POST /auth/logout, sign up with session.signup, and call account.confirm when session.get answers confirmed: false. Guests: session.guest when store.get answers guestCheckout: true.
5. Cart: cart.get, cart.add, cart.set, cart.remove, and cart.update for buyers or cart.contact for guests, plus the cart choice after sign-in when both carts hold items.
6. Quote and checkout: cart.get `{ "quote": true }`, then checkout.start. When state is pending_payment or needs_action, send the buyer to redirectUrl and call checkout.confirm when they return; otherwise poll checkout.status.
7. Orders: orders.list and orders.get.
8. On every refusal, show the buyer the message from the answer; it is written for buyers.

Acceptance checks. Run each one against the sandbox and show the user the requests and responses, with secrets redacted:
- store.get answers 200 for the host; a request without X-Storefront-Host answers 400 VALIDATION.
- A cart.add with a stale expectedRevision answers 409 CONFLICT, and the application re-reads the cart instead of failing.
- cart.get `{ "quote": true }` answers quoteReady: true with a quoteFingerprint for a cart with an address and a payment method.
- checkout.start reaches pending_payment or complete; sending it again with the same idempotencyKey does not create a second order, and checkout.status `{ idempotencyKey, quoteFingerprint }` finds the attempt.
- The signed-in buyer sees the new order in orders.list.
- The production build's client assets contain neither the API key's secret nor the string X-API-Key.

You are installing Kentro Pixel on the user's website: the browser SDK, wired to the site's consent manager, so page views and the site's key events reach Kentro with each visitor's consent.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/docs/kentro-pixel.md
- https://docs.kentro.io/docs/pixel-quickstart.md
- https://docs.kentro.io/docs/pixel-browser-sdk.md
- https://docs.kentro.io/docs/pixel-events.md
- https://docs.kentro.io/docs/pixel-consent-privacy.md

Ask the user for these before writing code:
1. The site's framework, and where the shared head or root layout is rendered.
2. The Pixel property's public key, from Kentro GO: `Pixel`, the `Properties` tab, the property, the `Install` tab. Production properties have pk_live_ keys; staging and development properties have pk_test_ keys. A public key is meant to be visible in the page.
3. Which Kentro environment the property lives in: production (collector https://pixel.kentro.live) or Kentro staging (collector https://pixel.kentro.dev).
4. The consent manager the site uses, and how its categories map to Kentro's purposes: analytics, marketing and functional.
5. Whether the site sends a Content-Security-Policy, and which events matter beyond page views (sign-ups, add to cart).

Rules:
- Only the public key goes in the page. Never put a Pixel server key (sk_...) or its secret in browser code.
- Install the queue stub before the SDK script, exactly as the snippet on the `Install` tab (or GET https://apis.kentro.live/pixel/v1/properties/:id/snippet) shows. Load https://pixel.kentro.live/sdk/v1/kentro-pixel.js (or the .dev host) with data-key, or call `kentroPixel('init', { key, endpoint })`.
- Report consent at init and on every change with `kentroPixel('consentChanged', { analytics, marketing, functional, policy_version, source })`, with granted or denied for each purpose. Without analytics consent, events are recorded as suppressed by design: never work around it.
- Never send identity claims (subject_ref) from the browser, and never put emails, phone numbers or other personal data in event properties. A signed-in visitor is identified only through an identity token the user's server signs, as the Browser SDK page describes.
- Use only event names and properties from the taxonomy (GET https://apis.kentro.live/pixel/v1/event-schemas), and validate custom events before shipping.
- With a CSP, allow the collector host in script-src and connect-src, and allow the inline stub with a nonce or hash.
- No fingerprinting and no ad-blocker workarounds.

Steps:
1. Add the stub and the SDK script to every page (the root layout), or the script loader with init.
2. Translate the consent manager's state into consentChanged on load and on every change.
3. Single-page apps: after auto-init the SDK tracks route changes. Confirm it, and do not add duplicate page views.
4. Add the site's key events with the event names from the Events page.
5. Ask the user to check that the property's allowed origins (the `Domains` tab) list the site's hosts.

Acceptance checks. Run each one and show the user the evidence:
- In the browser's network tab, POST `<collector>/v1/events` answers 202 with one result per event, status accepted (or suppressed before consent).
- Before consent, the newest events show processing_status suppressed_consent in the property's `Debugger` tab (or GET https://apis.kentro.live/pixel/v1/events/debug?propertyId=...&limit=20 with credentials holding pixel:read). After analytics consent, marketing.page_viewed shows pending or processed.
- The `Health` tab (GET /v1/ingestion/health?propertyId=...) shows no new rejections, and any reason code it lists is fixed.
- Every custom event passes the property's `Validate` tab or POST /v1/event-schemas/validate.
- The browser console shows no CSP violations, and no server key appears in the site's code.

You are sending server-side events from the user's backend to Kentro Pixel: authoritative facts such as commerce.order_paid and refunds. Revenue reporting trusts these facts only when they come from a server source.

Read first. Fetch https://docs.kentro.io/llms.txt and these pages:
- https://docs.kentro.io/docs/ai-agent-instructions.md (rules you must follow)
- https://docs.kentro.io/docs/kentro-pixel.md
- https://docs.kentro.io/docs/pixel-server-api.md
- https://docs.kentro.io/docs/pixel-events.md
- https://docs.kentro.io/docs/pixel-consent-privacy.md

Ask the user for these before writing code:
1. The backend language and framework, and where payment success and refunds are recorded.
2. A server key for the Pixel property, created in Kentro GO on the property's `Keys` tab (or with POST https://apis.kentro.live/pixel/v1/properties/:id/server-keys). The secret is shown once. Ask the user to store the key id (sk_...) as KENTRO_PIXEL_KEY_ID and the secret as KENTRO_PIXEL_SECRET in the environment, never in the chat or the browser.
3. The collector: https://pixel.kentro.live for production or https://pixel.kentro.dev for Kentro staging.
4. Which business events to send, mapped to event names from the Events page.

Rules:
- POST each batch to `<collector>/v1/server/events` with Content-Type: application/json and three headers: X-Kentro-Key-Id with the key id; X-Kentro-Timestamp with the current Unix time in seconds; X-Kentro-Signature with sha256= followed by the hex HMAC-SHA256 of `"<timestamp>.<raw body>"` keyed with the secret. Sign the exact bytes you send: serialize the body once.
- The timestamp must be within 300 seconds of Kentro's clock, or the request is refused with TIMESTAMP_STALE. A wrong signature is refused with SIGNATURE_INVALID.
- Give every event a stable event_id derived from the business fact (for example the order id plus the event name), so a retry is deduplicated. Kentro deduplicates event ids for at least 14 days. Never generate a new id for a retry.
- event_name is lowercase and dotted (commerce.order_paid). occurred_at is ISO-8601, no more than 7 days in the past or 5 minutes in the future. Each event stays under 32 KB.
- Money follows the event schema in integer minor units; floating-point money is rejected. Read the schemas from GET https://apis.kentro.live/pixel/v1/event-schemas and check events with POST /v1/event-schemas/validate before sending.
- Send consent and identity fields as the Server API and consent pages describe, and never send personal data the schema does not ask for.
- Send after the database commit, from a queue or outbox, so a crash neither loses nor double-sends an event. Retry network errors, 429 and 5xx with backoff and the same event_id.

Steps:
1. A signer module, with a unit test against a fixed timestamp, body and secret.
2. A sender that batches events, posts them, and logs the receipt_id and each event's status.
3. Hooks on payment success and refunds that enqueue the events.
4. A dead-letter path for events that keep failing, with their reason codes.

Acceptance checks. Run each one against Kentro staging or a test property and show the user the requests and responses, with secrets redacted:
- One signed commerce.order_paid event answers 202 with results[0].status accepted.
- The same event sent again answers status duplicate and creates no second record.
- A request whose timestamp is 10 minutes old is refused with TIMESTAMP_STALE, and one with a wrong signature with SIGNATURE_INVALID.
- The event appears in the property's `Debugger` tab with source_type server.
- No server secret appears in code, logs or client assets.

You are helping the user connect this AI client to Kentro MCP, Kentro's remote MCP server. Through it you act as the user in their Kentro workspace, with exactly their permissions, through Kentro Assistant.

Read first:
- https://docs.kentro.io/docs/mcp-overview.md
- https://docs.kentro.io/docs/mcp-connect-claude.md (Claude on the web and Claude desktop)
- https://docs.kentro.io/docs/mcp-connect-coding-agents.md (Claude Code, Codex and other clients)

Facts:
- Production URL: https://apis.kentro.live/kiq/v1/copilot/mcp. Kentro staging URL: https://apis.kentro.dev/kiq/v1/copilot/mcp.
- Remote Streamable HTTP server with OAuth 2.1 sign-in in the browser. There is no package to install, no API key and no token to paste. Never ask the user for their Kentro password.
- The connection belongs to the workspace the user approves it in. A user of several workspaces connects once per workspace.

Ask the user:
1. Which AI client this is, if you cannot tell.
2. Production or Kentro staging.
3. Their workspace key: the first part of their Kentro address (acme in acme.kentro.app). The sign-in page asks for it.

Steps:
- Claude Code: run `claude mcp add --transport http kentro-copilot <URL>`. Then ask the user to run /mcp, select kentro-copilot and complete the browser sign-in.
- Codex: run `codex mcp add kentro-copilot --url <URL>`. Codex discovers the OAuth server and opens the browser sign-in on first use.
- Claude on the web or Claude desktop: you cannot add the connector yourself. Tell the user to open Settings, then Connectors, choose Add custom connector, paste the URL and confirm.
- Any other client: check that it supports remote MCP servers over Streamable HTTP with OAuth 2.1, dynamic client registration and PKCE, and that its redirect URI is https or loopback. If it does not, tell the user it cannot connect; Kentro MCP accepts no API keys or static tokens.
- In the browser, the user enters the workspace key, clicks Continue, signs in, and clicks Approve on the page titled Connect to Kentro Assistant.

Verify, and show the user the results:
- Call getSessionContext and report the workspace name and the user the connection acts as.
- Make one read-only request, for example a summary of today's orders with a direct tool, or ask askCopilot what it can help with in this workspace.
- Tell the user where to see and revoke the connection: Kentro IQ, Assistant, Assistant Settings, panel Connect your AI tools (MCP), Active connections.

If something fails:
- "This connection request has expired": start again; a request lasts 10 minutes.
- "Your workspace's billing needs attention": an admin resolves billing in Kentro first.
- "This workspace is out of Copilot credit": an admin tops up in Billing.
- "Rate limit exceeded. Retry in ...": wait the time shown.
- Only knowledge base and tutorial tools appear: the user's permissions limit the assistant to Help Center content; an admin can change that.

Do not change other MCP servers in the client's configuration, and do not store tokens yourself: the client stores them.