Use the Enad MCP server when an agent needs live Enad context, docs routing, Search-backed storefront data, DAM metadata, or governed catalog and media changes.

Connect

Connect an MCP-capable client over Streamable HTTP:

https://mcp.enad.io/mcp

For the public Worker endpoint, send initialize, tools/list, and tool calls with POST /mcp. Use HEAD /mcp only as a discovery probe; it returns the OAuth challenge in WWW-Authenticate. GET /mcp and DELETE /mcp return 405 with Allow: POST, so do not model hosted clients around long-lived session reads.

Use the hosted custom domain for normal client setup. Public client examples should point at https://mcp.enad.io/mcp.

OAuth discovery lives at:

• /.well-known/oauth-protected-resource/mcp
• /.well-known/oauth-authorization-server/mcp
• /.well-known/openid-configuration/mcp

The protected-resource document advertises the /mcp resource, the matching issuer, supported scopes, default scope, public tools, and the auth note. The authorization metadata exposes the authorization-code grant, refresh tokens, and device codes. It also includes dynamic client registration, PKCE S256, token endpoint auth methods, and the device authorization endpoint.

Read the issuer, authorization endpoint, token endpoint, device authorization endpoint, and registration endpoint from the metadata for the MCP endpoint you are connecting to. Do not hard-code issuer or token URLs from examples, logs, or screenshots; those values can move independently of the stable https://mcp.enad.io/mcp resource URL.

Hosted metadata currently advertises docs.search and docs.get_route_guidance as public tools, catalog:read as the default delegated scope, and shopper:read, customer read/lookup/admin/share scopes, and dam:read as optional delegated scopes.

Codex setup

For Codex, use the Enad App or connector OAuth flow when it is available. That path lets Codex open the browser handoff, store and refresh the delegated token, then retry protected tools after approval.

Raw remote MCP configuration can still check endpoint metadata and public docs tools:

[mcp_servers.enad]
url = "https://mcp.enad.io/mcp"

Treat that snippet as a reachability check. It is not the complete protected-tool setup. Without the connector-owned OAuth provider, protected calls can fail with an authentication challenge instead of opening Codex's approval button.

Ready means all of these are true:

1. The client reads protected-resource metadata from the MCP endpoint.
2. The connector UI or connection prompt opens Enad OAuth approval.
3. Browser approval completes in the matching app environment.
4. Codex returns with a cached delegated token.
5. A protected read tool such as auth_get_current or context_get_current succeeds.

Start without signing in

Use public routing tools before any account read or change. They work without OAuth or a bearer token, and they should still work as anonymous docs lookups when the client has an expired token cached.

Sign in for protected tools

Protected tool families use delegated bearer authentication. Let the MCP client follow OAuth discovery instead of pasting tokens manually.

The default scope is:

• catalog:read

Optional scopes are:

• shopper:read
• customers:read
• customers:lookup
• customers:admin
• customers:share
• dam:read

Keep delegated scopes read-oriented. The hosted OAuth metadata does not advertise a broad catalog write scope. Catalog and media changes use preview, browser approval, apply when needed, then audit. Approved catalog proposals receive a one-time downstream grant instead of a long-lived delegated write scope.

When auth is missing, expired, or inactive, the server returns an OAuth challenge and status that tells the client to connect or reconnect.

Do not stop at initialize or tools/list. Those calls can succeed while protected tools still need OAuth. Verify readiness with browser approval and a protected read call.

Public docs tool calls are intentionally more forgiving than protected tools. If a client has a stale or inactive bearer token cached, docs lookup should still behave as anonymous unless the result requires protected account context.

Choose the active app context

After sign-in, inspect the actor and active app:

Keep the team and app explicit before catalog, media, DAM, customer, or order work. That context determines which downstream data each protected tool may read or change.

Find and run capabilities

Capability discovery should be the first step before choosing a workflow:

• search_capabilities finds read, draft, dry-run, and write capabilities.
• execute_capability runs read and draft capabilities.

Use the model-safe names returned by tools/list when you call tools. Display names such as changes.preview and changes.apply may appear in descriptions, but the callable tool names are changes_preview and changes_apply.

Use search_capabilities as a precise registry query instead of a keyword search. Filter by:

• query for natural-language or exact capability-id matching
• namespace such as search, catalog, commerce, media, routing, merchandising, identity, or customer
• mode: read, draft, dryRun, or write
• mutation status, riskTier, and phase
• limit up to 200 results

Set includeInputFields: true to expose accepted top-level input names. Set includeDetails: true to expose mutation details such as status, risk tier, phase, preview tool, apply tool, permission group, and tags.

Capability status controls what an agent may do next:

For write work, require both status: "implemented" and concrete previewTool / applyTool values before routing through changes_preview or changes_apply. Descriptor-only capabilities can still have schemas and input fields; those fields describe the proof gate, not an executable API request.

Implemented mutation families cover bounded catalog metadata and relationships, merchandising, variants, variant groups, stock, pricing, warehouses, bundles, DAM, media-control, and media-delete workflows.

Some high-risk families can appear as descriptor-only proof gates. Examples include identity, customer-owned data, smart listings, broad product lifecycle, broad order, and raw upload. Treat those as non-executable until discovery returns an implemented preview/apply route.

Capability discovery returns the execution state for each write workflow. Use that returned status to route the next call: implemented capabilities can use their preview/apply tools, while descriptor-only, deferred, blocked, and out-of-scope entries are not executable write paths. Shopper and standalone DAM reads should not be treated as write surfaces; DAM writes route through Management-owned DAM capabilities when discovery returns an implemented workflow.

Use identity and customer namespace searches to inspect proof-gate status for account, organisation, wishlist, saved-cart, customer-file, role, and customer-group workflows. Do not execute those families unless discovery returns status: "implemented" with concrete preview and apply tools.

execute_capability validates params against the discovered capability schema, but only for read and draft modes. Dry-run and write capabilities are intentionally blocked from execute_capability; use the preview/apply lifecycle for those changes.

If capability discovery or execution returns a documentation reminder, follow it before continuing. The server tracks whether docs were consulted in the session and may suggest docs.get_route_guidance or docs.search with a focused query before catalog reads or writes.

Change data safely

Use this lifecycle for catalog and media changes:

1. Resolve the active context with auth_get_current or context_get_current.
2. Find the matching capability with search_capabilities.
3. Validate or preview the change with validate_catalog_change or changes_preview.
4. Review the returned change set, proposal, approval metadata, and impact summary.
5. Complete the browser approval step when the preview returns an approval URL or approval request.
6. Poll the proposal, changed resource, or audit trail after browser approval.
7. Call changes_apply only when the workflow still needs an explicit apply call.
8. Read audit_get after apply and verify the changed resource through the owning API or read tool.

For proposal-backed workflows, browser approval can complete the write and is normally the apply step when the proposal includes both an approval request and a one-time write grant. Enad Auth sends the approval decision back to MCP with the request id, status, actor, and decision time. MCP then matches the request to the stored proposal, redeems the grant for short-lived catalog write access, and applies the supported workflow.

Callback auto-apply is intentionally narrow. The callback accepts pending, approved, denied, expired, and consumed statuses. Unknown request ids are treated as best-effort no-ops, non-approved statuses only update proposal state, and unsupported workflows are not applied by the callback path. Supported callback auto-apply covers tag-name, tag-name batch, and DAM image-attribute batch proposals after the approval grant is redeemed. Other approved workflows can still require changes_apply or a later implemented apply path. After browser approval, poll the proposal, changed resource, or audit trail before assuming a second changes_apply call is required.

Approval URLs are one-time request artifacts. Generate a fresh request from the same environment as the MCP endpoint instead of reusing a saved link. Keep the Enad Auth issuer, app approval page, callback origin, and shared service secrets in that environment too. Mixed environments can make the browser page unable to load the request or post the decision back to the right service.

Hosted approval callbacks need both a public callback origin and a callback secret. Public hosted operation uses the hosted MCP origin with the matching Enad Auth issuer and app approval page. The callback secret configured in Enad Auth must match the MCP server secret; do not expose either secret in docs, prompts, logs, or browser URLs.

Public docs versus exact contracts

MCP helps agents choose and operate against Enad surfaces. It does not replace the owning contracts:

• API paths, methods, request bodies, and responses stay in API references and OpenAPI specs.
• Search schema, operations, fragments, variables, and nullability stay in Search reference.
• Media upload, metadata, relationship, delete, and DAM endpoint details stay in Media and DAM references.
• Event names, envelope fields, and payload schema IDs stay in the Event catalog.

Use MCP docs tools for routing, use read tools for live context, and use references before writing code that depends on exact fields.

Operator deployment boundaries

Operator service setup is not the public Codex connector setup. Public docs should keep the hosted endpoint, OAuth discovery, connector handoff, and safe tool workflow clear without publishing local service environment variables.

For hosted operation, keep every connection on one deployment. Match these values:

• Enad API base URL
• Enad Auth issuer and approval page
• MCP callback origin
• callback and approval-decision secrets

Keep each connection in one environment. Use matching MCP endpoint, Auth issuer, app approval page, callback origin, and shared secrets. A mixed setup can break browser approval. It can also post the decision back to the wrong service.

Public setup should not depend on local development modes, direct-apply bypasses, tool-decision shortcuts, or header-based local auth. Use the hosted connector and OAuth flow for protected tools.

Related docs

Continue with Agent quickstart, API, Search, and Events agent guide, Media, or Enad app auth.md.