MCP OAuth: Implementing OAuth 2.0 for MCP Servers

OAuth Basics for MCP

OAuth 2.0 is the industry-standard authorization framework that allows a user to grant an application limited access to their account on another service, without sharing their password. In the MCP context, OAuth enables AI agents to access services like Google Workspace, GitHub, Slack, and Microsoft 365 on behalf of a user, with explicit consent and scoped permissions. The MCP specification recommends OAuth 2.1, which mandates PKCE (Proof Key for Code Exchange) for all clients, removes the implicit grant flow, and requires exact redirect URI matching. These improvements close several known attack vectors in the original OAuth 2.0 spec, including authorization code interception and redirect URI manipulation. For MCP deployments, OAuth serves double duty: it authenticates the user's consent to grant access, and it provides the time-limited tokens that the MCP gateway uses to make tool calls on the user's behalf.

The OAuth Implementation Flow for MCP

The MCP OAuth flow has several steps. First, the user initiates a connection through the MCP gateway's interface, selecting the service they want to connect (e.g., Google Drive). The gateway redirects the user to the service provider's OAuth consent screen, requesting specific scopes (e.g., drive.readonly). The user reviews and approves the scopes. The service provider redirects back to the gateway with an authorization code. The gateway exchanges this code for an access token and a refresh token using its client credentials. Both tokens are encrypted and stored in the gateway's secure credential store. The gateway then maps these tokens to the user's account and their agent permission profiles. When an agent makes a tool call, the gateway retrieves the appropriate access token, validates it is not expired (refreshing if necessary), and includes it in the request to the MCP server. The agent never sees the raw token -- it only uses its session identifier.

Token Management Strategies

Access tokens should be treated as short-lived and expendable. Most providers issue tokens with a 1-hour expiry. The gateway should proactively refresh tokens before they expire (e.g., at the 50-minute mark) to avoid mid-session failures. Refresh tokens are long-lived and must be protected aggressively: encrypted at rest with AES-256, stored in a dedicated secrets store (not in the same database as application data), and rotated on every use when the provider supports it. For multi-service environments, each service connection should have isolated token pairs -- a compromise of one service's credentials should not affect others. Implement token revocation webhooks so that when a user revokes access from the service provider's side, the gateway is immediately notified and cleans up the stale tokens. Monitor token refresh failures: three consecutive failures likely indicate the user has revoked access, and the agent should be notified gracefully rather than retrying indefinitely.

Security Considerations for MCP OAuth

The state parameter in the OAuth flow must be cryptographically random and validated on return to prevent CSRF attacks. Always use PKCE, even for confidential clients -- it adds defense in depth against authorization code interception. Store client secrets in environment variables or a secrets manager, never in code or configuration files committed to version control. Implement strict redirect URI validation: the callback URL must match exactly, with no wildcards or partial matches. For high-security environments, consider using DPoP (Demonstration of Proof of Possession) tokens, which bind access tokens to a specific client key pair, preventing token theft and replay. Audit your OAuth scope requests regularly -- over-scoped connections are the most common MCP security gap. If an agent only needs to read calendar events, the OAuth connection should request only the calendar.readonly scope, not the full calendar scope.

Frequently Asked Questions

Related Terms