# How the MCP OAuth Provider Registration Flow Works in OpenSEO

> Explore the MCP OAuth provider registration flow in OpenSEO. Learn how it validates custom scopes, issues time-bound tokens and manages session state via transport middleware.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: internals
- Published: 2026-07-21

---

**OpenSEO implements a custom OAuth 2.0 authorization-code flow for its Machine-Cognition Platform (MCP) that validates custom scopes, issues time-bound tokens, and persists session state through dedicated transport middleware.**

The `every-app/open-seo` repository provides a production-ready implementation of an MCP (Machine-Cognition Platform) OAuth provider. Understanding the MCP OAuth provider registration flow is essential for developers integrating third-party clients with OpenSEO's AI-powered SEO capabilities. The implementation centers on [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts), which orchestrates scope validation, metadata generation, and token issuance alongside [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) for request security.

## MCP OAuth Architecture and Constants

The OpenSEO MCP OAuth system extends standard OAuth 2.0 patterns with custom constants defined in [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts). These constants govern the registration behavior and security boundaries:

- `MCP_OAUTH_SCOPES`: An array declaring all supported scopes for MCP clients (lines 12-13)
- `MCP_SCOPE`: The core permission required for any MCP client authorization
- `MCP_ROUTE`: The base path (`/mcp`) where MCP endpoints are mounted
- `MCP_ACCESS_TOKEN_TTL_SECONDS`: Access token validity period (24 hours)
- `MCP_REFRESH_TOKEN_TTL_SECONDS`: Refresh token validity period (30 days)

## Step 1: OAuth Metadata Exposure

When a client initiates registration, the provider first exposes OAuth metadata to enable discovery. In [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts) at lines 420-431, the system constructs a metadata object containing supported scopes, the authorization endpoint, and token lifetimes derived from the constants defined at lines 45-47.

The metadata includes the `MCP_OAUTH_SCOPES` constant, which lists every scope available to MCP clients. The core `MCP_SCOPE` permission serves as the mandatory baseline—any registration request lacking this scope fails immediately during the validation phase.

## Step 2: Scope Validation and Intersection

After user authorization, the provider calculates granted scopes by intersecting the client's requested permissions against the supported list. At lines 241-247 of [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts), the code validates that requested scopes exist within `MCP_OAUTH_SCOPES`.

If the essential `MCP_SCOPE` is absent from the intersection, the registration process terminates with an authorization error. Only scopes that intersect with the supported list are granted to the client.

## Step 3: Token Issuance and Session Persistence

Once scope validation succeeds, the provider issues tokens using the TTL constants defined at lines 45-47. The generated access token (valid for `MCP_ACCESS_TOKEN_TTL_SECONDS`) and refresh token (valid for `MCP_REFRESH_TOKEN_TTL_SECONDS`) are stored in the OAuth session store.

These tokens attach to the user's session under the `MCP_AUTH_CONTEXT_PROP` property defined in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts), enabling persistent authentication across subsequent API calls without re-authorization.

## Step 4: Request Validation via Transport Middleware

Every authenticated MCP request passes through the transport middleware defined in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts). At lines 52-56, this middleware extracts the auth context from `MCP_AUTH_CONTEXT_PROP`, verifies token validity against the session store, and confirms the presence of `MCP_SCOPE`.

Requests missing valid authentication or the required scope receive a 403 Forbidden response before reaching business logic. This enforcement occurs on every request to the `MCP_ROUTE` (`/mcp`) endpoints configured in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts).

## Implementation Example

The following TypeScript example demonstrates how a third-party client initiates the MCP OAuth provider registration flow and exchanges the authorization code for tokens:

```typescript
// 1️⃣ Build the authorization URL
const authUrl = `${process.env.NEXT_PUBLIC_BASE_URL}/auth/mcp?` + new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://yourapp.com/callback',
  response_type: 'code',
  scope: 'mcp',                     // must include the core MCP_SCOPE
}).toString();

// 2️⃣ Direct the user to the URL (e.g., open a popup)
window.open(authUrl, '_blank');

// 3️⃣ After the user authorizes, your redirect handler receives the code
//    Exchange the code for tokens
async function exchangeCode(code: string) {
  const resp = await fetch('/auth/mcp/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      code,
      grant_type: 'authorization_code',
      redirect_uri: 'https://yourapp.com/callback',
    }),
  });
  const { access_token, refresh_token, expires_in } = await resp.json();
  // Store tokens securely and use them for MCP API calls
  return { access_token, refresh_token, expires_in };
}

```

## Summary

- **Scope Validation**: OpenSEO validates requested scopes against `MCP_OAUTH_SCOPES` at lines 241-247 of [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts), requiring the mandatory `MCP_SCOPE` for all registrations.
- **Token Configuration**: Access tokens expire after 24 hours and refresh tokens after 30 days, configured at lines 45-47 of the OAuth provider file.
- **Metadata Exposure**: The provider exposes OAuth metadata including supported scopes and endpoints at lines 420-431 to facilitate client discovery.
- **Middleware Enforcement**: The [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) middleware validates tokens and scopes at lines 52-56 on every request, returning 403 for unauthorized access.
- **Session Persistence**: Authenticated sessions store tokens under `MCP_AUTH_CONTEXT_PROP`, enabling seamless API access across the `/mcp` route.

## Frequently Asked Questions

### What scopes are required for MCP OAuth registration in OpenSEO?

Every MCP OAuth registration must include the `MCP_SCOPE` constant defined in [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts). This core permission grants basic access to Machine-Cognition Platform endpoints. The provider intersects requested scopes against the `MCP_OAUTH_SCOPES` array at lines 241-247, and registration fails if `MCP_SCOPE` is absent from this intersection.

### How does OpenSEO validate MCP OAuth tokens on each request?

Request validation occurs in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) at lines 52-56. The transport middleware extracts the authentication context from `MCP_AUTH_CONTEXT_PROP`, verifies the token's validity and expiration, and confirms the presence of `MCP_SCOPE`. Invalid or missing credentials trigger an immediate 403 Forbidden response before the request reaches MCP business logic.

### What is the token lifetime configuration for MCP OAuth?

According to lines 45-47 of [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-provider.ts), access tokens remain valid for 24 hours (`MCP_ACCESS_TOKEN_TTL_SECONDS`) while refresh tokens persist for 30 days (`MCP_REFRESH_TOKEN_TTL_SECONDS`). These TTL values balance security with user convenience for long-running SEO automation workflows.

### Where does OpenSEO store MCP authentication context?

The system persists MCP authentication data under the `MCP_AUTH_CONTEXT_PROP` property within the user's session, as defined in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts). This property stores the access token, refresh token, and granted scopes after successful registration, allowing the transport middleware to retrieve credentials without requiring re-authentication for each API call to the `/mcp` route.