Connector OAuth

Connect an MCP client to one Tringify store or developer organization using OAuth authorization code flow with PKCE. The user chooses the target and approves access in their Tringify account. The Store MCP edits eligible orders and manages Markets, products, collections, categories, attributes, brands, vendors, tags, files, store languages, pages, policies, and blog posts, tags, categories, authors, comments, comment settings, blog index SEO, and menus. It also reads custom domains and email sender settings, edits records in DNS zones Tringify hosts, sets the customer reply-to address and checks suppressed recipients. Files include separate Media and Site Assets libraries and a direct-upload workflow. Store connections can also add a theme bundle to a storefront as a new, unpublished theme. The developer resource manages the organization's theme listings: upload a bundle, publish a version, and install it into a development store. App operations are not exposed yet.

In the Codex app, open Settings > MCP servers > Add server. Name it Tringify, choose Streamable HTTP, and enter https://api.tringify.com/mcp/store. Save and restart when prompted, then select Authenticate. Sign in to Tringify, choose a store, review the requested access, and approve. Complete the browser flow on the same computer that started it.

If you use the Codex CLI, add the server with the command below. Follow its sign-in prompt; if authentication is still needed, run codex mcp login tringify. The app and CLI share MCP settings on the same host, so use either setup method.

Start a new conversation and ask Codex to list five tags in the connected store. This read needs store:products:read; the create, update, and delete workflow also needs store:products:write. Tringify hosts the MCP server. No API key or Tringify package is needed. See the connection guide and GitHub quickstart for setup, examples, and troubleshooting.

Discover the authorization server from resource metadata or the WWW-Authenticate header on an unauthenticated resource request. Its issuer is https://api.tringify.com/oauth/connectors; authorization-server metadata is available at https://api.tringify.com/.well-known/oauth-authorization-server/oauth/connectors. Send the exact resource URL, without a trailing slash, as resource in authorization and token requests. A token issued for one resource is rejected by the other.

Use an HTTPS Client ID Metadata Document URL as client_id. The document must return JSON with the same client_id, a client_name, an exact redirect_uris list, and token_endpoint_auth_method: "none" or token_endpoint_auth_methods_supported containing none. The URL must be public HTTPS on port 443, with no query, fragment, or redirect. Tringify reads the document when authorization starts.

Clients that use dynamic registration can POST the same metadata, without client_id, to /oauth/connectors/register. The JSON response supplies a generated client_id. No client secret is issued. Client names allow up to 100 characters; a client can register up to 10 callbacks. Callbacks must use HTTPS, except HTTP loopback callbacks for local clients. Callback URLs match exactly except for the port of HTTP callbacks on the literal loopback addresses 127.0.0.1 and [::1]. Native clients may choose an available port at sign-in; the scheme, host, path, query, and URL encoding must still match. The token exchange requires the exact callback used in that authorization request, including its port. Fragments and embedded credentials are rejected.

Use a new random state and PKCE verifier for each attempt. The verifier must contain 43–128 unreserved characters. Compute code_challenge as unpadded base64url of the verifier's SHA-256 hash. Check the returned state and iss before exchanging code. A denial returns error=access_denied. The pending approval expires after 10 minutes; an issued authorization code expires after 5 minutes and can be exchanged once.

Store credentials securely and send access tokens only to their resource URL in Authorization: Bearer …. These credentials are not Store API tokens and are not accepted by ordinary Store Admin or Developer API endpoints. This public-client flow rejects client secrets and client assertions. It does not return an ID token.

connection:read permits the MCP connection and is the default if scope is omitted. On the Store resource, request store:products:read for list/get and store:products:write for create/update/delete. Request both for catalog reads and writes. Media reads require store:files:read; Media writes and upload operations require store:files:write. Site Assets use store:online_store.site_assets:read and store:online_store.site_assets:write instead. Pages and Policies require store:pages:read or store:pages:write. Blog posts, tags, categories, and authors require store:blog:read or store:blog:write. These permissions are independent of Products access. Translations additionally require store:settings.languages:read or store:settings.languages:write, alongside the resource permission. Product mutations affecting Gift Card products also require store:gift_cards:write where the API requires Gift Card write access. A context-only Store connection can read universal reference data and the four reference guides. Store catalog, file, language settings, and currency settings require their own permissions. Storefront theme tools require store:online_store.storefronts:read to list storefronts and themes and store:online_store.storefronts:write to upload and import a theme. On the developer resource, organization:themes:read lists theme listings and versions and organization:themes:write uploads bundles, publishes versions and installs them into development stores; get_connection_context needs only connection:read. organization:apps:read and organization:apps:write can be approved but no tool uses them yet. Scope names for store permissions use store:<permission>; developer organization permissions use organization:<permission>. Request only the scopes needed by available tools. Approval binds a connection to one user, client, resource, and selected target. The effective scope set cannot exceed either that approval or the user's current permissions. An owner approving a narrow scope still creates a narrow connection.

Each resource request checks current membership and permissions. Removing a member or disconnecting the tool invalidates its access. Rejoining does not restore the removed connection. Account, store, subscription, and organization restrictions still apply. An operation already authorized before a disconnect may finish; disconnecting does not reverse completed work.

Access tokens last up to 15 minutes. Refresh tokens last up to 30 days, and the connection expires after 90 days even if refreshed. POST grant_type=refresh_token, client_id, refresh_token, and the original resource to the token endpoint. An optional scope can narrow access, never enlarge it. Save the new refresh token atomically and discard the previous one. Serialize refreshes for a connection: reusing a consumed refresh token revokes that connection, including its newly issued tokens. An uncertain refresh response requires a new authorization rather than replaying the old token. Approving an update to an existing connection starts a new connection lifetime when its authorization code is successfully exchanged.

Revoking either token disconnects its entire connection. An unknown token or a token from another client receives the same successful response without exposing its status. Users can also disconnect in Accounts > Connected tools; store and developer organization owners can disconnect their team's connections for their target. Other connections from the same client are unaffected.

Start a new OAuth authorization from the connected tool, requesting the access it needs. Keep the same registered client and resource. On the Tringify approval screen, select the same store or developer organization and choose the existing connection. Review the permissions marked as new and any access that will be removed, then select Update access. If more than one connection matches, select the connection you intend to update. Creating a separate connection remains an explicit choice.

Approval alone does not change the existing connection. The update takes effect when the client successfully exchanges the new authorization code with its PKCE verifier. The connection keeps its ID; its previous access and refresh tokens stop working, and the returned tokens carry the approved access allowed by the user's current permissions. Replace stored credentials atomically and refresh tool discovery. A rejected or abandoned authorization leaves the current connection unchanged.

A disconnected or expired connection cannot be updated. If the connection changes after the approval screen was loaded, start authorization again. Accounts > Connected Tools provides Update access guidance; authorization starts in the tool so that it can receive the replacement credentials. For Codex, use codex mcp login <server-name> with the existing server name. Token refresh never adds permissions.

Audited changes are attributed to the Tringify user who authorized the connection. In the store audit log, the source is API and the credential label is Connected tool: <client name>. A team member's connection records that member as the actor; it does not act as the store owner. File uploads keep the same user and tool attribution. Normal resource audit behavior applies; reading data does not create a mutation audit entry.

Use Streamable HTTP with JSON responses. The server is stateless and does not issue Mcp-Session-Id; GET and DELETE on the MCP resource return 405. Follow MCP initialization and version negotiation. Send Content-Type: application/json, an Accept header containing application/json and text/event-stream, the negotiated MCP-Protocol-Version, and the Bearer token on each POST.

The Store tool list reflects the connection's approved access and the user's current permissions. Discovery includes only tools allowed by the connection. Product read access exposes catalog reads; write access exposes their mutations. File tools appear for the permitted library access. Write permission does not imply read permission. A previously listed tool can become unavailable after permissions change. Calling a known tool without its required scope returns HTTP 403 with an insufficient_scope challenge. Obtain new consent for additional permissions; refreshing cannot add them. Newly released tools within an already-approved permission can appear after the client refreshes discovery. Existing Products read/write approvals therefore cover the new Brand, Vendor, and Attribute tools; file access requires its own approval.

All five tools act on the store chosen during OAuth approval. There is no store ID argument. Unknown arguments, invalid types, and non-positive IDs are rejected. Tag names, slugs, duplicates, and store limits follow the Tags API contract. Creating a tag does not assign it to products. Bulk actions and tag translations are not exposed as MCP tools in this release.

List returns one page with tags, total, limit, sort_by, sort_direction, has_next, has_previous, and cursors when available. Pass an exact returned next_cursor or previous_cursor for another page. Reset the cursor when search or sorting changes. Dates use ISO timestamps. Results appear in both structuredContent and JSON text content with success, data, and any success code/message.

For deletion, first call delete_tag with only id. An unused tag is deleted immediately. If product assignments or collection rules are affected, the tool returns isError: true and a CONFIRMATION_REQUIRED error containing impact warnings and a confirmation token. Present that impact to the user. After approval, call again with the same id, confirmed: true, and the exact confirmation_token. Do not automatically confirm. A confirmed deletion removes those tag references while retaining the products. The normal tag audit entries and webhook events also apply to MCP writes.

Validation and domain failures are tool results with isError: true and a public error containing code, message, and any details or public params. Preserve these fields, especially confirmation details. A timeout can leave a write's outcome unknown: inspect the affected record before issuing another write. Requests are bounded by the gateway body limit and the same resource limits as the API. Binary uploads go directly to their signed upload URL. MCP writes are not automatically retried.

List/get requires store:products:read; create/update/delete requires store:products:write. Names, slugs, descriptions, SEO, template assignments, uniqueness and store limits follow the corresponding Brands and Vendors contracts. Omitted update fields remain unchanged. Null is rejected. Empty description or SEO strings clear those fields after their translations are removed; empty image_id clears the image. On create, an omitted or empty slug is generated from the name. A slug change creates a redirect unless create_redirect is false.

Binding a non-empty image_id requires store:files:read in addition to product write access. Use an existing Media image ID; Site Assets and external URLs are not accepted as catalog image references. Clearing or omitting the image does not require file read access. Deletion uses the same impact-confirmation flow as Tags and keeps the related products. Lists return brands or vendors with totals and cursor metadata; get/create/update return the resource.

Attribute list/get requires product read; mutations require product write. Each option accepts label, value, color, file_id, and sort_order; label is required. A missing or blank value is generated from its label. Swatches require color, and image options require a Media image. Update options also accept id: keep existing IDs and include every option to retain. An omitted or zero ID creates an option; leaving an existing option out requests its removal. The service blocks removal of options in use. Parent fields omitted from the update stay unchanged.

Read the attribute immediately before editing. Send its exact revision as expected_revision; a stale revision fails without overwriting the newer attribute. Do not invent a revision or blindly repeat a rejected update. Subtype is immutable, and slug edits are blocked while products or storefront filters use the attribute. New option image references require Files read access; retaining the same image on the same existing option does not. The Attributes reference describes option validation and limits. Creating an attribute does not create variants.

Every file tool requires library: "media" or library: "site_assets". File IDs are UUID strings. The selected library controls the required permission and the files the operation may access; choosing another library does not widen a grant. File get/update/delete also enforce the library of the stored record. Files cannot be moved between libraries through these tools.

Use get_file_limits and get_storage_quota before uploading. create_file_uploads returns data.intents, with each intent's intent_id, filename, status, signed url, required headers, and expires_in. PUT the original bytes directly to that URL using those headers; do not send base64 file contents in tool arguments. Then call finalize_file_uploads with the same library and intent IDs. Check get_file_upload_status while processing. A ready result includes the validated file; a failure includes its error. Preparing or uploading bytes alone does not make the file ready to attach. Signed upload URLs are temporary credentials and must not be published.

The upload flow keeps the existing file-content validation, quota checks, library rules and automatic preview processing. File tools do not provide image editing, byte replacement, preview retry, bulk deletion, translations, or metafield operations. A file deletion can return CONFIRMATION_REQUIRED; show the complete impact before confirming, and never override a required-reference block. See Files for the library contract.

These tools cover the documented Store API operations for Products, Collections, Categories, Attributes, Languages, Currencies, Markets, Domains, Email, Pages, Policies, Blog Posts, Blog Tags, Blog Categories, and Blog Authors that accept merchant credentials: resource management, variants, quantity pricing, supported bulk actions, collection rules and product lists, ordering, metafields, and translations. Product purchase-requirement endpoints require an installed app identity and are not exposed through a user connection. They cannot be enabled by selecting additional user permissions.

Tool arguments use the documented API field names, with path and query parameters alongside JSON body fields. The variant path parameter is named variant_id. Do not provide an Authorization header, store ID, user ID, or app identity. The attribute list also accepts summary: true to omit full option arrays. Optional idempotency_key is available on content translation writes. File tools use library: media|site_assets in place of the API file type, and media_type for its media query filter. All listed operations follow the corresponding Store API validation and mutation behavior. Omitted fields, explicit nulls, validation, confirmations and partial bulk results follow the corresponding API operation. Check the returned success and failure lists for bulk changes.

Variant creation and core edits happen through the parent product's create or update tool, using variants, new_variants, and removed_variant_ids as documented. There is no standalone create-variant tool. Use list_catalog_metafield_definitions to discover accessible definitions before writing values by namespace and key. Metafields follow the connected user's merchant access; the connection has no installed app identity.

Language tools use store:settings.languages:read or store:settings.languages:write; Products access is not required. list_available_languages lists supported locale codes and list_languages returns the enabled set, default language and current plan limit. Supported-language discovery is universal reference data; list_available_languages requires a valid Store connection, without Languages settings access. set_languages replaces the complete enabled set when locales is supplied; omit it to leave the set unchanged. Always retain the default language. Adding a language does not publish it on an individual storefront or translate content automatically. Storefront assignments remain a separate Online Store action.

Removing a language, changing the default, and resetting translations can permanently remove translation data. Present the backend impact and obtain approval before resending the same operation with confirmed: true and its confirmation_token. A storefront-assigned language cannot be removed until its assignments are removed. delete_language_translations resets one enabled non-default language without disabling it. The same plan limits, validation, audit records, and language webhook events as the Languages API apply.

Menus require store:menus:read or store:menus:write, independently of Pages and Blog. Menu reads include full trees, lazy item pages, and whole-menu item search. A save requires the revision returned by a read and exactly one of a complete items tree or ordered ops; a stale save returns MENU_SAVE_CONFLICT. Preserve existing item IDs to retain translations. Deleting a menu removes every item; deleting an item removes its descendants. Menu item titles have individual and batch translation tools, with additional Languages access. Pages include list, search, create, update, delete, bulk deletion, translations, metafields, and definition discovery. Policy records are a fixed set: use the policy type for get/update and the policy UUID for translations. There are no create or delete policy tools. Use list_page_metafield_definitions or list_blog_metafield_definitions for accessible content definitions; Products permissions are not needed for those discovery tools.

Blog Posts include scheduling fields, single and bulk changes, categories/tags assignment and removal, translations, and metafields. Removing an author used by posts requires reassign_to_author_id; use the existing author workflow rather than deleting or orphaning those posts. Blog Authors have no translation endpoints. Attaching a post featured image or author avatar also requires Files read access. Blog Comments support listing, status counts, single and bulk moderation, and permanent deletion. Comment settings expose comment mode and moderation. Blog index SEO includes source and translated fields; assigning its social image also requires Site Assets read access.

Content translation tools are available for products, variant titles, collections, categories, attributes, attribute options, tags, brands, vendors, pages, policies, blog posts, blog tags, blog categories, and supported product, variant, category, collection, brand, vendor, page, blog post, and blog category metafields. Product, collection, category, attribute, attribute-option, tag, brand, vendor, page, policy, blog post, blog tag, and blog category translations also have batch tools. Variant titles and metafield translations use their individual tools. Files do not currently expose translation tools through MCP. AI translation jobs and CSV translation imports or exports are not included.

Currency configuration reads require store:settings.currencies:read; writes require store:settings.currencies:write. These are independent of Products and Languages access. The base currency remains immutable; plan restrictions, decimal rates, omitted-field preservation, automatic-rate rules and cleanup confirmations follow the Currencies API. Show returned impact before confirming currency data removal; historical commerce and financial records are preserved.

Domain and DNS reads require store:settings.domains:read; DNS record changes require store:settings.domains:write. Records Tringify keeps for the storefront connection and email sending stay locked, and adding or removing domains stays in Store Admin. See Domains & DNS. Email settings reads require store:settings.email:read; setting the customer reply-to address requires store:settings.email:write, and a new address takes effect once its inbox confirms the link Tringify sends. See Email.

Markets reads require store:markets:read; writes require store:markets:write. These permissions are independent of Products and store Currencies access. Request both for workflows that read and write. Existing connections add them through an approved access update, then refresh tool discovery. All 107 documented Markets JSON operations are exposed: core markets, countries and currency assignments; tax classes/zones/rates/price rules; discounts and settings; shipping; duties; COD; connected payment-provider availability/discounts; checkout limits, fees and ordering.

Market path IDs are named market_id, tax_class_id, tax_zone_id, tax_rate_id, discount_id, currency_id, binding_id, rule_id, method_id, zone_id and fee_id as applicable. Tool input schemas distinguish numeric values, decimal strings, amount maps and nullable fields. Read the current market, assigned currencies, limits and complete specialist definition before editing. Market PATCH preserves omitted fields; specialist PUT operations follow their documented replacement behavior. A tax-rate batch containing creates must not be retried automatically. CSV tax imports/exports and their jobs are available in Store Admin and mobile.

The Markets Markdown resource at https://dev-docs.tringify.com/store-api/markets/markets explains country/currency dependencies, exact amounts, tax/duty setup, shipping modes, COD restrictions, discounts and checkout, confirmation and bulk behavior. It is public integration guidance and contains no store data. Use tool discovery for current input fields. Markets tools use the same native Store API validation, ownership, audit and webhook behavior.

Use get_order and get_order_edit_options to read the current version, editable fields and line quantity floors. Read access is store:orders:read; preview, shipping quotes and applying require store:orders:write. Neither scope grants the other. An existing connection must approve additional access before these tools become available.

Build the draft with order_version, item changes and optional updates for contact, addresses, shipping or the manual order discount. Existing item prices and manual line discounts use set_price and set_discount. These operations do not reassign the customer account or change the order currency. Fulfillment or item refunds lock prices, discounts and delivery details. Existing promotion identities remain recorded; this flow does not add coupon codes.

Use list_order_edit_shipping_options for configured delivery methods, then preview_order_edit. Review totals, before/after fields, refund choices and affected fulfillment apps. Pass the matching preview_token and a stable idempotency_key to apply_order_edit. For a timeout, retry only the identical request with the same key. For a stale version or quote, read and preview again before applying. list_order_edits returns saved history. The Store API reference documents the complete order edit contract.

The Store MCP exposes four read-only Markdown resources: https://dev-docs.tringify.com/store-api/reference, https://dev-docs.tringify.com/store-api/reference/phone-numbers, https://dev-docs.tringify.com/store-api/reference/addresses, and https://dev-docs.tringify.com/store-api/markets/markets. Clients can list and read them with the existing Store connection. They explain lookup data, accepted phone formats, exact country/subdivision values, postal validation and resource-specific address requirements. Country tables are obtained with the lookup tools; they are not duplicated in the guides. Reference resources are bounded to 32 KiB each.

Universal reference tools expose countries, subdivisions, supported languages and currencies, timezones, phone-code metadata, number-format defaults, address formats and the Store API scope catalog. They do not expose a store's enabled language or currency configuration and do not change access. The scope catalog lists requestable API scopes, not the connection's approved permissions. Prefer a country-specific address lookup for a form; complete reference catalogs have no pagination.

Brands, Vendors, and Tags expose their core record operations plus individual and batch translations; Brands and Vendors also expose metafield translations. Files expose the listed library and direct-upload operations. This page does not imply that every endpoint for those resources has an MCP equivalent. Normal resource webhook events still apply to MCP mutations; these tools do not manage webhook subscriptions.

On /mcp/developer, the read-only get_connection_context tool accepts an empty arguments object. It returns connection_id, client_id, client_name, client_origin, user_id, target (kind, id, name), resource, current scopes, and connection_expires_at. It contains no token or unrelated store/organization data.

Developer tools act on the organization chosen during approval; there is no organization argument, and IDs are UUIDs. The listing must already exist: create listings, set pricing and submit for review in the Developer Portal. A published version cannot change. Each successful upload, publish or install is recorded in the organization's activity log with the user and Connected tool: <client name>. The same tokens also work on the Developer API theme routes (below).

Importing never changes the live theme; preview and publish the imported theme in Store Admin. These tools cannot activate, edit or delete themes. PUT the bundle bytes directly to the signed URL with the returned headers; never send file contents as tool arguments.

A developer organization token (resource https://api.tringify.com/mcp/developer) is also accepted as Authorization: Bearer on these Developer API routes at https://api-dev.tringify.com/api/v1: GET /org/themes, GET /org/themes/{listingId}, GET /org/themes/{listingId}/versions, POST /org/themes/upload, POST /org/themes/upload/finalize, POST /org/themes/upload/status, POST /org/themes/{listingId}/versions and POST /org/themes/{listingId}/versions/{versionId}/install. Reads need organization:themes:read; the others need organization:themes:write. Every other Developer API route rejects connector tokens. Store tokens are rejected. Send no cookies with a bearer request; X-Organization-ID, if sent, must be the connected organization.

The Tringify CLI uses these routes and the storefront theme tools. Its client ID is the metadata document at https://api.tringify.com/oauth/connectors/clients/tringify-cli, with a loopback callback on 127.0.0.1.

An account can have up to 100 active connections. Revoke unused connections before creating more. Client metadata documents are limited to 16 KiB, client IDs to 2,048 characters, and requested scope lists to 256 unique scopes. Tokens and codes are opaque; do not parse them or write them to logs.