The oh-my-openagent system provides a robust implementation for handling authenticated Model Context Protocol (MCP) servers. This implementation supports OAuth 2.0 with Proof Key for Code Exchange (PKCE) and Dynamic Client Registration (DCR), ensuring secure authorization flows for third-party MCP tools and services.
Authenticated MCP servers require a standardized way to handle user authorization without exposing long-lived credentials. The system implements a flow that allows users to authenticate against MCP servers, manage tokens locally, and perform "step-up" authentication when higher privilege levels are required by a specific tool or resource.
Sources: packages/omo-opencode/src/features/skill-mcp-manager/manager.ts15-33 packages/omo-opencode/src/features/mcp-oauth/provider.ts12-24 packages/omo-opencode/src/features/mcp-oauth/provider.test.ts26-63 packages/omo-opencode/src/features/mcp-oauth/dcr.ts1-10 packages/omo-opencode/src/features/skill-mcp-manager/oauth-handler.ts6-13
The following diagram illustrates the interaction between the SkillMcpManager, the McpOAuthProvider, and the remote MCP server during an authenticated request.
Sources: packages/omo-opencode/src/features/skill-mcp-manager/manager.ts106-158 packages/omo-opencode/src/features/skill-mcp-manager/oauth-handler.ts6-13 packages/omo-opencode/src/features/skill-mcp-manager/connection.ts3-6 packages/omo-opencode/src/features/skill-mcp-manager/cleanup.ts4-10
To support various MCP server implementations without hardcoding secrets, the system utilizes Dynamic Client Registration (DCR). Upon the first login attempt to a new server, the agent registers itself to obtain a client_id packages/omo-opencode/src/features/mcp-oauth/dcr.ts1-10
The PKCE (Proof Key for Code Exchange) extension is used to mitigate authorization code injection attacks. This is critical as the CLI operates in a public client environment where client secrets cannot be securely stored. The system generates a code_verifier and a corresponding code_challenge using SHA256 packages/omo-opencode/src/features/mcp-oauth/provider.test.ts51-63
The SkillMcpManager maintains a state of active connections and prevents race conditions during setup using a pendingConnections map packages/omo-opencode/src/features/skill-mcp-manager/connection.ts37-40 It distinguishes between local stdio and remote http (SSE) connections packages/omo-opencode/src/features/skill-mcp-manager/connection.ts154-157
The manager also handles session-specific disconnection races, ensuring that if a session is disconnected while a connection is in flight, the resulting client is disposed of correctly packages/omo-opencode/src/features/skill-mcp-manager/connection-race.test.ts142-162
Tokens are persisted locally to avoid frequent re-authentication. The McpOAuthProvider interacts with a storage layer to save OAuthTokenData which includes the access token, refresh token, and expiration timestamp packages/omo-opencode/src/features/mcp-oauth/provider.test.ts192-210
refresh_token if a request fails with an authentication error packages/omo-opencode/src/features/skill-mcp-manager/manager.ts134-143Sources: packages/omo-opencode/src/features/skill-mcp-manager/connection.ts37-40 packages/omo-opencode/src/features/skill-mcp-manager/connection-race.test.ts142-162 packages/omo-opencode/src/features/skill-mcp-manager/manager.ts134-143 packages/omo-opencode/src/features/mcp-oauth/provider.test.ts192-210 packages/omo-opencode/src/features/skill-mcp-manager/http-client.ts63-77
Certain MCP tools may require "Step-up Authentication" if a specific action requires a higher scope than what was initially granted.
withOperationRetry catches the error and calls handleStepUpIfNeeded packages/omo-opencode/src/features/skill-mcp-manager/manager.ts123-128McpOAuthProvider initiates a new login flow with the expanded scopes.forceReconnect to apply the new credentials packages/omo-opencode/src/features/skill-mcp-manager/cleanup.ts3-10Sources: packages/omo-opencode/src/features/skill-mcp-manager/manager.ts15-33 packages/omo-opencode/src/features/skill-mcp-manager/types.ts77-90 packages/omo-opencode/src/features/mcp-oauth/provider.test.ts67-70
The system provides CLI utilities for managing these authenticated sessions docs/reference/cli.md41:
| Command | Action | Implementation Detail |
|---|---|---|
mcp oauth login | Initiates PKCE flow | Triggers McpOAuthProvider.login() via factory packages/omo-opencode/src/features/skill-mcp-manager/manager.ts31 |
mcp oauth logout | Clears local tokens for a server | Disconnects sessions via SkillMcpManager.disconnectSession packages/omo-opencode/src/features/skill-mcp-manager/manager.ts49-51 |
mcp oauth status | Checks connectivity and token validity | Validates via isConnected and getConnectedServers packages/omo-opencode/src/features/skill-mcp-manager/manager.ts171-177 |
Sources: packages/omo-opencode/src/features/skill-mcp-manager/manager.ts49-55 packages/omo-opencode/src/features/skill-mcp-manager/manager.ts171-177 packages/omo-opencode/src/features/skill-mcp-manager/manager.ts31 docs/reference/cli.md41
Refresh this wiki