mcp-oauth-remote-gateway

OAuth authentication fails on remote MCP servers because the built-in automated browser flow cannot capture loopback callbacks due to address mismatches on headless gateways. This requires performing the OAuth 2.1 with PKCE flow manually to establish a connection.

To manually authenticate a remote MCP server, follow the step-by-step procedure to perform the OAuth 2.1 with PKCE dance manually. You must securely create and place the OAuth tokens and client information files so the gateway can authenticate without automated browser intervention.

You can test OAuth token validity for a headless MCP gateway by running the included diagnostic scripts. These scripts smoke-test tokens and identify whether connection failures are caused by a circuit breaker, session revocation, or expired credentials.

Automated OAuth flows are not usable for MCP servers on headless remote machines because loopback callbacks are unreachable. You must use a manual OAuth flow to configure the necessary token files and enable secure token exchange for the agent runtime.

The best way to manage OAuth credentials for a headless MCP gateway is through manual file-based credential provisioning. This involves guiding the secure creation and placement of token files to ensure seamless integration and validate token persistence without user intervention.

An MCP gateway connection may drop after manual OAuth due to expired credentials, a triggered circuit breaker, or session revocation. Use diagnostic scripts to validate connection health and token persistence to identify the exact cause of the failure.