# Admin MCP authentication

Admin MCP uses the same **OAuth 2.0** access tokens as the [Admin REST API](/apis-and-tools/rest-api/authentication). There is no separate MCP API key.

For the authorize → token → resource walkthrough, see the [Authentication guide](/get-started/authentication). This page covers what Admin MCP adds on top of that flow.

## OAuth endpoints

| Endpoint | URL |
| --- | --- |
| Authorization | `https://account.finqu.com/oauth2/authorize` |
| Token | `https://account.finqu.com/oauth2/access_token` |
| Resource | `https://account.finqu.com/oauth2/resource` |
| Authorization server metadata | `https://account.finqu.com/.well-known/oauth-authorization-server` |
| Admin MCP | `https://mcp.finqu.com/mcp` |

Supported grants include `authorization_code`, `refresh_token`, and `client_credentials`. PKCE `S256` is advertised for public clients. See [Discovery](#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:

```json
{
  "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](#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.

> **Info:**
  Admin MCP validates the access token and forwards it when admin tools call the Admin REST API. Scopes on the token therefore apply to both MCP tools and the underlying HTTP calls.

## 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](./admin#sales-channel).

## 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.

| Scope | Admin MCP tool groups |
| --- | --- |
| `profile` | `list_channels` (also granted by `sales_channel_read` / `sales_channel_write`). `get_profile` is available on any merchant token |
| `catalog_read` / `catalog_write` | Products, relations, product groups, manufacturers, taxes, deliverers, reviews |
| `inventories_read` / `inventories_write` | Inventory status, transfers, warehouses (`list_storages`) |
| `customers_read` / `customers_write` | Customers, groups, segments, tags |
| `sales_read` / `sales_write` | Orders, refunds, order notes |
| `marketing_read` / `marketing_write` | Discounts, marketing messages, email designer, social posts (`webstore` and `pos`) |
| `discounts_read` / `discounts_write` | Same marketing permissions as `marketing_read` / `marketing_write` |
| `analytics_read` / `analytics_write` | Analytics, forecasts, keyword/content SEO tools |
| `media_read` / `media_write` | Images and videos |
| `themes_read` / `themes_write` | Theme files, sections, blocks, settings, section groups |
| `settings_read` / `settings_write` | Policies; merchant and billing address |
| `sales_channel_read` / `sales_channel_write` | `list_channels`, navigation, pages, articles, channel address and organization category, `list_calendar_events` |

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](./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:

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

Typical messages:

| Message | Cause |
| --- | --- |
| `Authorization header required.` | Missing `Authorization`, or the header is not `Bearer …` |
| `Invalid access token.` | Token failed OAuth validation |
| `Merchant account is not active.` | Merchant on the token is not active |
| `User is not an authorized staff member of this merchant.` | HTTP `403`. The user is not staff on that merchant |

Missing or foreign `channel_id` values are MCP tool errors, not HTTP `401` or `403`. See [Sales channel](./admin#sales-channel).

See [Discovery](#discovery) for RFC 8414 / RFC 9728 details.