# Connect a coding agent to Shoptype Shoptype's remote MCP interface lets coding agents configure product integrations and inspect delivery activity using the same seller and market operator permissions as the web app. ## Connection - Transport: Streamable HTTP (stateless) - Production URL: `https://app.shoptype.com/mcp` - Authentication header: `Authorization: Bearer ` - Protocol: current MCP and older Streamable HTTP clients supported. Sign in to Shoptype and open **Developer access** near the bottom of the workspace (also linked from the footer). Name a token, choose read-only, seller or operator permissions and an expiry, then click **Create token**. Copy the token immediately; it is shown once. The list shows actual expiry and last use, with a **Revoke** button. Tokens are limited by your current account permissions and the lifetime of your Intergraph sign-in. Recreate a token after expiry or invalidated sign-in. Raw Intergraph human tokens remain supported for existing clients. Store the token in your client's secure environment or secret settings. Do not paste it into chat, a repository or URL. Browser cookies, GM service tokens, Stripe keys and product API keys do not authenticate MCP. Shoptype checks revocation, expiry, the underlying Intergraph identity and current workspace authority on every request. Developer tokens do not implement OAuth discovery. ### Codex Add this secret-free entry to your Codex configuration: ```toml [mcp_servers.shoptype] url = "https://app.shoptype.com/mcp" bearer_token_env_var = "SHOPTYPE_MCP_TOKEN" ``` Set `SHOPTYPE_MCP_TOKEN` in the environment that launches Codex, using the token you copied, and restart Codex. A variable set inside an already-running agent's shell does not update its MCP client environment. See [official Codex MCP documentation](https://developers.openai.com/codex/mcp). For Claude Code or another bearer-compatible remote HTTP client, use the same endpoint and an `Authorization: Bearer ` header supplied through its secure configuration. Configure your MCP client's remote server URL and bearer header using those settings. Clients that require automatic OAuth rather than a configured bearer header need an adapter. Start by asking the agent to read `shoptype://integration-guide` and call `shoptype_account`. ## Seller workflow 1. Discover markets and organizations. Create an organization and apply if needed. 2. Wait for the market operator to approve and set up your seller player. 3. Discover GM capabilities, create an encrypted product API source and bind an integration to your verified seller player. 4. Read `shoptype://configuration`, then save a catalog and fulfillment revision. Product credentials belong only in the source credentials input. 5. Use the web app to authorize background operations and connect Stripe. MCP provides instructions for this human step; it does not grant background access. 6. Ask the operator to enable test purchases. Publish the catalog and complete a Stripe TEST purchase. 7. Inspect delivery activity, run replay checks and check certification. Activation requires complete, unexpired evidence and the market's current payment and commercial configuration. ### Mapping the purchase amount Use `checkout_money.amount` and `checkout_money.currency` when a product API needs the original purchase total. Shoptype derives these from every order in the prepared checkout, in integer minor units. Each order amount already includes its quantity. These values remain available on refunds and disputes whose payment details may be absent. Map the refund amount separately from `event.payload.amount`; `checkout.orders.0.money.amount` covers only the first cart line. ### Verify the recipient before payment For products requiring an existing verified account, register a named `recipient_check` endpoint alongside `readiness` and delivery endpoints in each environment. Add `recipient_check: {"url":"https://product.example/recipient-check"}` to the saved revision. The UI exposes this under Delivery setup. Shoptype sends an authenticated POST with `{"email":"buyer@example.com"}` before preparing checkout. The read-only product endpoint must return HTTP 200 with `{"eligible":true}` to continue. False, unavailable, or malformed responses block checkout before payment. Credentials use the product connection's authentication; never put them in the URL. Readiness can advertise `recipient_check_required:true` to require this configuration. Test and production checks must use their own registered endpoints and are included in configuration promotion comparisons. ## Operator workflow Market owners can inspect applications, approve or reject, and provision sellers when the GM supports that operation. They can inspect integration activity, enable test purchases, pause sales and activate certified revisions. Seller credentials remain private. Approval, payment connection, testing and production activation are distinct steps. A successful test purchase alone does not complete certification. Connecting an MCP client does not activate a seller or change any market. Production activation is a separate operator action after certification and commercial acceptance. All tool inputs are validated. Organization management, current GM ownership and seller membership are checked by the same handlers used by the UI. Tool errors omit internal exceptions and returned data omits credential fields. ## Production workflow tools - `shoptype_create_price`: create a one-time price in the seller's processor account when the GM advertises `create-product-price`. Amounts are integer minor units. Price creation does not charge a buyer. If unsupported, create the price through the seller's Stripe UI and supply its `price_ref`; never give the agent a platform Stripe key. - `shoptype_integration_status`: read launch blockers, background authorization expiry, product readiness and certificate validity, including supporting test evidence. These checks describe eligibility for the next activation; the current integration status is reported separately. - `shoptype_inspect_checkout`: provide an integration ID and checkout ID to trace observed payment, product delivery and market acknowledgment. Inspect lifecycle entries for subsequent refunds or disputes. - `shoptype_retry_job`: operators can retry only jobs accepted by the existing safe-retry rules. An unknown product outcome requires evidence and reconciliation in the operator UI; the tool cannot mark it delivered. - `shoptype_source_change_impact`: inspect direct users and production certificates that depend on a product source before changing credentials or pairing. ### Payment is separate from fulfillment `payment: not_observed` means Shoptype has not received the payment event. It does **not** mean the buyer has not paid. Verify the existing checkout in the GM or processor; do not charge again. Check that the GM's webhook receives **connected-account** events for seller-direct charges. A connected, payment-ready Stripe account does not prove that its webhook is working. Webhook health is reported as unverified when no authoritative health information is available; MCP does not repair processor configuration. Delivery is confirmed when the product API acknowledges the action. Market acknowledgment is a separate stage; a failed relay does not justify granting the product again. ### Retire tests without invalidating production evidence Promoted production certification depends on the exact supporting test certificate and its frozen Shoptype product binding. Rotating stored test credentials, changing pairing, replacing supporting evidence, or allowing it to expire can invalidate that dependency. Inspect source-change impact first. The UI previews affected production integrations before credential or pairing changes. After successful promotion, revoke the **test** background authorization in Shoptype and disable the actual test product API or its isolated infrastructure. Preserve the frozen Shoptype source binding and test records used by production certification. Keep production authorization active for delivery. Infrastructure shutdown is an operator action outside MCP; do not remove shared databases or other markets. ### Errors and expiry Tool failures retain `isError: true` and human-readable text, with additive `structuredContent.error` fields: `code`, `message`, `retryable`, and `next_step`. Unexpected failures during a mutation are uncertain outcomes: inspect current state before repeating the operation. Database date fields are ISO strings; legacy numeric expiry fields retain their existing format, and status reports provide ISO expiry values. background authorization, developer access and certification have separate expiries. Secrets remain redacted from responses.