mcp-remote-appengine

This is a fork of mcp-remote with changes:

• Acess Token is now automatically refreshed 5 minutes before the expiry
• I have internally changed the reference library @modelcontextprotocol/sdk to reflect issue https://github.com/geelen/mcp-remote/issues/128
• --static-oauth-client-info-base64 option added where json parameter is now encoded as base64

OAuth Token Refresh Enhancements

Overview

The NodeOAuthClientProvider has been enhanced with automatic token refresh capabilities to prevent authentication failures due to expired access tokens.

Key Improvements

1. Automatic Token Expiration Tracking

• Tokens are now stored with an issued_at timestamp
• The system can accurately calculate when tokens expire
• Accounts for time drift and provides a 30-second buffer before expiration

2. Automatic Token Refresh

• When tokens() is called and the access token is expired, it automatically attempts to refresh using the refresh token
• Uses the MCP SDK's refreshAuthorization function
• Seamlessly handles the OAuth metadata discovery and token exchange

3. Enhanced Token Validation

• New checkTokenValidity() method for diagnostic purposes
• Improved debug logging with expiration details
• Better error handling for invalid or malformed tokens

4. Graceful Degradation

• If token refresh fails, expired tokens are automatically cleared
• Forces re-authentication flow instead of repeated failures
• Maintains backward compatibility with existing token files

5. Path‑aware OAuth discovery builds an invalid URL

• If Authorization server has realm in path the path builded in mcp is incorrect

Usage

The enhancements are transparent to existing code:

// Existing code continues to work unchanged
const provider = new NodeOAuthClientProvider(options)
const tokens = await provider.tokens() // Now automatically refreshes if needed

// New diagnostic capability
const validity = await provider.checkTokenValidity()
console.log('Token expires in:', validity.timeLeftSeconds, 'seconds')

Token Storage Format

Tokens are now stored with an additional issued_at field:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "issued_at": 1643723400000
}

Debugging

Enable debug mode to see detailed token refresh information:

npx tsx proxy.ts https://your-server.com --debug

Debug logs include:

• Token expiration calculations
• Refresh attempt details
• Success/failure notifications
• Timing information

Error Handling

The system handles various failure scenarios:

1. No refresh token: Clears expired tokens and forces re-auth
2. Refresh endpoint unavailable: Falls back to full re-authentication
3. Network failures: Retries based on underlying HTTP client behavior
4. Invalid refresh token: Clears all tokens and forces re-auth

Migration

Existing token files will continue to work:

• Tokens without issued_at fall back to using expires_in directly
• First token refresh will add the issued_at timestamp
• No manual migration required