# MCP Authentication

The Resolve MCP supports two authentication paths. Choose based on who is connecting:

|  | Web App Authentication | Machine-to-Machine (M2M) |
|  --- | --- | --- |
| **Who it's for** | A person using a native AI assistant (Claude, ChatGPT) | Automation: custom MCP clients, headless agents, server-side jobs |
| **How it works** | Interactive OAuth 2.0 sign-in with your Resolve dashboard login, including Google login | OAuth 2.0 Client Credentials — exchange an MCP access key for a bearer token |
| **Login required** | Every individual must have their own Resolve account and sign in to connect | Never interactive — the token impersonates the account owner on every call, with no additional auth |
| **Identity & scope** | The signed-in user's dashboard roles and permissions | The account that owns the access key — merchant or partner — limited by the key's scopes |
| **Revoke** | Disconnect the connector in the AI assistant | Revoke the key in Merchant Dashboard |


## Which one should I use?

- **A person working in Claude or ChatGPT** → Web App Authentication. Each person signs in with their own Resolve account, so permissions follow the individual user.
- **Automation — an unattended agent, backend service, or custom MCP client** → M2M. Only use it if the credential is protected behind your own gated access (secrets manager, permissioned CI, locked-down service account) — remember, anyone holding the token can act as the account owner with no further auth.
- **Both at once is fine** — for example, your AR team uses Claude via Web App Authentication while a nightly automation reconciles invoices with an M2M token.


## Get an MCP API access key

Create an MCP API access key to configure authentication for your MCP integration.

![Resolve dashboard OAuth settings](/assets/resolve-dashboard-oauth.8a7ff4d45c4fc17fc9e664421caf28b968c30a42e82c9b82f47f4f0008e1b950.9bb1daa4.png)

1. Visit [**Merchant Dashboard Integrations**](https://app.resolvepay.com/dashboard/integrations).
2. Enable **OAuth** if it is not already enabled. OAuth is required for both Web App Authentication and M2M.
3. Click **Generate MCP access key**.
4. Select the authentication type.
5. If you select **M2M**, choose the permission for the key. A `:read` scope grants read tools only; a `:write` scope grants read and write tools. The scopes offered depend on your account type:
  - Merchant accounts — `merchant:read` / `merchant:write`
  - Marketplace partner accounts — `marketplace_partner:read` / `marketplace_partner:write`
  - Single-merchant partner accounts — `single_merchant_partner:read` / `single_merchant_partner:write`
6. Copy the `client_id` and `client_secret` immediately. The secret is shown only once.


Permissions are available only for M2M tokens. MCP access keys are distinct from standard API keys: a standard v3 API key cannot be used with the MCP, and an MCP key cannot call the REST API. Store the credentials securely.

A partner account's key grants the partner tool set — the `partner-v1` tools, in place of the merchant ones. See the [Tool Reference (Partner)](/guides/mcp-tools-partner) for the full list.

## Web App Authentication

Use this when a person connects Resolve inside Claude, ChatGPT, or another OAuth-capable MCP client. Each person signs in with their own Resolve account (including Google login), and every tool call is checked against their dashboard role — a read-only login gets read-only tools. Deactivating the user cuts off their MCP access.

Because Resolve does not support Dynamic Client Registration, every client — Claude and ChatGPT alike — must be given OAuth client credentials. Generate a **Web App** access key ([above](#get-an-mcp-api-access-key)), then enter its `client_id` and `client_secret` in the connector's OAuth settings. On first connect the client redirects you to the Resolve login; after you approve, it stays connected with rotating refresh tokens.

### OAuth callback URLs

Some clients ask for — or display — an OAuth callback (redirect) URL during setup:

| Client | Callback URL |
|  --- | --- |
| Claude (claude.ai) | `https://claude.ai/api/mcp/auth_callback` |
| Claude (claude.com) | `https://claude.com/api/mcp/auth_callback` |
| ChatGPT | Generated per connector — under **Advanced OAuth settings**, choose **User-Defined OAuth Client** and ChatGPT shows it (e.g. `https://chatgpt.com/connector/oauth/<connector-id>`) |


## Machine-to-Machine (M2M) Authentication

Use this path for automation: custom MCP clients, scheduled agents, CI jobs, or backends that call the MCP on your behalf. There is no login screen and no OAuth redirect — the client presents a bearer token on every request, and the MCP server simply validates it.

**The token impersonates the account owner every time it's used, with no additional authentication.** Whoever created the access key is the identity every M2M call runs as — there's no per-call sign-in, no MFA, and no way to distinguish which person or job triggered a given request beyond what you log yourself. Because of this, we recommend only using M2M when access to the credential itself is gated behind your own authentication and authorization controls (a secrets manager, a permissioned CI system, a locked-down service account) — not stored somewhere any team member can read and reuse it.

### 1. Get an MCP access key

Follow [Get an MCP API access key](#get-an-mcp-api-access-key) to create and securely store the `client_id` and `client_secret`.

### 2. Exchange the key for a bearer token

Send a `POST` request to `/api/access-keys/token` with `audience` set to `mcp`:

```bash
curl https://app.resolvepay.com/api/access-keys/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<client_id>",
    "client_secret": "<client_secret>",
    "audience": "mcp"
  }'
```

Example response:

```json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 86400
}
```

The returned token is a JWT with `aud = https://mcp.resolvepay.com/mcp`, scoped to your merchant account.

### 3. Configure your MCP client

Point your client at the MCP URL and send the token as a bearer header. Example configuration (Claude Code / any `mcpServers`-style client):

```json
{
  "mcpServers": {
    "resolve": {
      "type": "http",
      "url": "https://mcp.resolvepay.com/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

Tokens expire (`expires_in` is in seconds) — mint a new one from the same key when needed. Revoked or expired keys cannot mint tokens.