Admin MCP authentication

Admin MCP uses the same OAuth 2.0 access tokens as the Admin REST API. There is no separate MCP API key.

For the authorize → token → resource walkthrough, see the Authentication guide. This page covers what Admin MCP adds on top of that flow.

OAuth endpoints

Supported grants include authorization_code, refresh_token, and client_credentials. PKCE S256 is advertised for public clients. See Discovery for RFC 8414 and RFC 9728.

Send the access token on every MCP request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Discovery

Authorization server metadata (RFC 8414) is public at:

https://account.finqu.com/.well-known/oauth-authorization-server

MCP OAuth clients start at the Admin MCP URL:

1. GET or POST https://mcp.finqu.com/mcp without Authorization
2. Read WWW-Authenticate for resource_metadata (RFC 9728)
3. Fetch protected-resource metadata (resource, authorization_servers)
4. Run authorization code plus PKCE against https://account.finqu.com

Protected-resource metadata is published at:

https://mcp.finqu.com/.well-known/oauth-protected-resource/mcp

The same document is also served at /.well-known/oauth-protected-resource. It identifies the resource and the authorization server:

{
  "resource": "https://mcp.finqu.com/mcp",
  "authorization_servers": ["https://account.finqu.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "profile",
    "sales_channel_read",
    "sales_channel_write",
    "catalog_read",
    "catalog_write",
    "sales_read",
    "sales_write",
    "customers_read",
    "customers_write",
    "partner:clients_read",
    "partner:clients_write"
  ],
  "resource_documentation": "https://developers.finqu.com"
}

That scopes_supported list is what discovery advertises, including partner scopes. A token may also carry the other Admin REST scopes in Scopes (marketing_*, themes_*, media_*, and the rest). Those scopes still gate which admin tool calls succeed. Partner tools are not part of this guide.

MCP URL

Connect every merchant to:

https://mcp.finqu.com/mcp

The OAuth resource response (GET https://account.finqu.com/oauth2/resource) includes merchant.endpoints.admin, merchant.endpoints.api, and a per-server merchant.endpoints.mcp. Those hosts are for the admin UI, the REST API, and internal routing. Admin MCP clients use https://mcp.finqu.com/mcp only.

Sales channel

OAuth tokens are merchant-scoped. Many admin tools are channel-scoped: their schemas advertise an integer channel_id. Call list_channels to discover ids when a tool requires one. get_profile and list_channels do not take channel_id.

list_channels requires profile, sales_channel_read, or sales_channel_write. Without one of those scopes the tool returns insufficient_scope.

Details and error text are on Admin MCP.

Scopes

Request the minimum REST scopes your agent needs. Write scopes include the matching read permission.

Admin MCP maps scopes to which tool calls succeed as follows. All platform admin tools still appear in tools/list for merchant OAuth tokens. Legacy aliases products_* → catalog_* and orders_* → sales_* still work.

A write scope is required for create/update/delete tools in that group. For example catalog_read allows get_product and search_products but not create_product. Creating or editing a marketing message requires marketing_write (or discounts_write, which grants the same marketing permissions).

Social tools succeed when the token has any of marketing view, create, or edit, so marketing_read covers them. Marketing messages and social tools run on webstore and pos channels.

The user’s admin role still applies: a staff user without product edit permission cannot call write product tools even if the token has catalog_write.

Some tools also require a plan feature (for example inventory transfers and product relation links). Those tools error at call time if the merchant’s plan does not include the feature.

See Tools for the full catalog.

Client approval and rate limits

• The OAuth client must be approved for the user (or auto-enabled). An unapproved client is rejected when an admin tool call is forwarded.
• If the client has a configured rate limit, excess forwarded tool calls return 429 with the message Too many requests.

Errors

Unauthenticated or invalid requests to https://mcp.finqu.com/mcp return HTTP 401, WWW-Authenticate, and:

{
  "error": "unauthorized",
  "message": "Authorization header required."
}

Typical messages:

Missing or foreign channel_id values are MCP tool errors, not HTTP 401 or 403. See Sales channel.

See Discovery for RFC 8414 / RFC 9728 details.