Authenticate with the Perk MCP server

This article explains how an AI client authenticates with the Perk Model Context Protocol (MCP) server so it can call tools on your behalf. The Perk MCP server uses the OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE), and supports Dynamic Client Registration (DCR), so most clients complete the whole flow with no manual setup.

How authentication works in Perk

The Perk MCP server authenticates AI clients using the OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE). The MCP server acts as a resource server, and a Django-based authorization server issues and validates tokens.

The client drives the flow. You do not build or host any of it yourself. The steps are:

1. The client discovers the OAuth 2.0 metadata from the server URL you configured.
2. The client registers itself using Dynamic Client Registration (DCR).
3. The client starts an authorization code flow with PKCE.
4. You complete sign-in and consent in the browser using your existing Perk credentials.
5. The client receives an access token and sends it on each tool call.

The access token is scoped to your role and your company's modules through role-based access control (RBAC). A client can only read what you could already access in Perk.

Register a client with Dynamic Client Registration

The Perk MCP server supports Dynamic Client Registration (DCR), defined in RFC 7591, so clients register themselves automatically. DCR lets a client obtain its own credentials at connection time instead of using a pre-registered client ID and secret.

Clients that support DCR need no manual client ID or secret. For example, the MCP Inspector connects with the client ID and secret fields left empty, and DCR handles registration.

Complete sign-in and consent in the browser

After a client starts the flow, you complete sign-in and consent in the browser. The client opens your browser to the Perk sign-in page, where you authenticate with your existing Perk credentials.

External authorization consent is required. You approve the access the client requests before the authorization server issues an access token. This step ties the token to your identity and to the scopes you approve.

Scopes

Scopes control which resources an access token can read. Perk uses colon-separated scope strings, and a client requests the scopes it needs during sign-in. The following scopes are verified for this release.

Downloading or polling a report — travel or spend — uses report:write, the same scope that generates it. The invoice, event, and card tools need no additional scope; access follows your existing Perk role and permissions. The card and transaction tools also require a Spend subscription.

Token lifetime, refresh, and revoke

The OAuth 2.0 client manages token lifetime and refresh for you, renewing the access token as needed without you re-authorizing each time. The Perk MCP server caps its stored OAuth state at 7 days; the validity of each access token is set by Perk's OAuth authorization server.

Environments

Connect production clients to the production server URL https://mcp.perk.com/api/mcp/mcp.

Next steps

• Connect a client to the Perk MCP server
• Perk MCP tools reference