How the MCP OAuth Provider Registration Flow Works in OpenSEO

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, which orchestrates scope validation, metadata generation, and token issuance alongside 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. 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 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, 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, 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. 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.

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:

// 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, 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 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. 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 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, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}