MCP OAuth Authorization Flow
Relevant source files
The following files were used as context for generating this wiki page:
The MCP OAuth Authorization Flow is a security mechanism within OhMyOpenCode designed to manage third-party access and authentication. It facilitates secure interactions with the Model Context Protocol (MCP) by implementing the OAuth 2.0 protocol, specifically utilizing Proof Key for Code Exchange (PKCE) to prevent authorization code injection and interception attacks.
This system is central to the project's ability to integrate with external tools and services while adhering to modern security standards. As of early 2026, the project notes that while third-party OAuth access has seen restrictions from providers like Anthropic, OhMyOpenCode maintains a standard implementation for users to manage their own credentials and access tokens.
Sources: README.md:91-115, src/features/mcp-oauth/provider.test.ts:7-15
PKCE Implementation and Security
The authorization flow relies heavily on PKCE (Proof Key for Code Exchange) to secure the exchange of the authorization code. This involves generating a cryptographically random code verifier and a corresponding code challenge.
PKCE Components
| Component | Description | Technical Detail |
|---|---|---|
| Code Verifier | A high-entropy cryptographic random string. | 32-byte random string, base64url-encoded. |
| Code Challenge | A challenge derived from the verifier. | SHA256 base64url digest of the verifier. |
| Challenge Method | The method used to derive the challenge. | Fixed to S256. |
Sources: src/features/mcp-oauth/provider.test.ts:6-41
The following sequence shows the initial URL construction for the authorization request:
Provider Configuration and Storage
The McpOAuthProvider class serves as the orchestrator for the flow. It handles the storage of sensitive data such as the code verifier and the resulting OAuth tokens.
Configuration Parameters
The provider is initialized with server information and client credentials:
- serverUrl: The base URL of the MCP server.
- clientId: The registered client ID for the application.
- scopes: An array of requested permissions (e.g.,
openid,profile). - redirectUri: The callback URL, defaulting to
http://127.0.0.1:19877/callback.
Sources: src/features/mcp-oauth/provider.test.ts:98-118, src/features/mcp-oauth/provider.test.ts:162-172
Token Persistence
OAuth tokens are persisted to the filesystem within the OpenCode configuration directory. The token data structure includes the following fields:
export interface OAuthTokenData {
accessToken: string;
refreshToken: string;
expiresAt: number; // Unix timestamp
}
Sources: src/features/mcp-oauth/provider.test.ts:143-152
Integration with the Prometheus Planning Agent
The OAuth flow is often triggered or managed during the planning phase of the Prometheus agent. Prometheus acts as a strategic consultant that gathers requirements before execution.
Research and Librarian Interaction
When Prometheus determines that a task requires external documentation or open-source implementation examples, it utilizes the librarian agent. If the required resource is protected, the OAuth flow ensures the agent has the necessary accessToken to perform searches via GitHub CLI or other authenticated APIs.
Sources: src/agents/prometheus/interview-mode.ts:150-170, sisyphus-prompt.md:126-140
Success and Verification
The authorization flow is considered successful once the tokens are securely stored and accessible to the executor agents (like Sisyphus). In the generated work plans, verification of authenticated features often includes:
- Checking for the existence of session tokens or cookies.
- Executing API calls (e.g., via
curl) and asserting201or200status codes. - Verifying that the
accessTokenallows access to protected resources.
Sources: src/agents/prometheus/plan-template.ts:175-195, src/features/mcp-oauth/provider.test.ts:153-159
Summary
The MCP OAuth Authorization Flow provides the secure foundation for OhMyOpenCode to interact with external services. By combining PKCE security, local token persistence, and integration with the Prometheus planning cycle, it ensures that agents can autonomously perform deep research and implementation tasks while maintaining strict security boundaries.