Static oauth client info (geelen#85)

* support optional static oauth client info instead of requiring dynamic client registration

* tweak README.md

* resolve merge conflicts

* add/document @ static oauth metadata/info filepaths

---------

Co-authored-by: William Hou <whou@hubspot.com>

Author: geelen

README.md

@@ -152,6 +152,37 @@ npx mcp-remote https://example.remote/server --transport sse-only
 - `http-only`: Only uses HTTP transport, fails if the server doesn't support it
 - `sse-only`: Only uses SSE transport, fails if the server doesn't support it
 
+### Static OAuth Client Metadata
+
+MCP Remote supports providing static OAuth client metadata instead of using the mcp-remote defaults.
+This is useful when connecting to OAuth servers that expect specific client/software IDs or scopes.
+
+Provide the client metadata as a JSON string or as a `@` prefixed filepath with the `--static-oauth-client-metadata` flag:
+
+```bash
+npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
+# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
+npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'
+```
+
+### Static OAuth Client Information
+
+Per the [spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#2-4-dynamic-client-registration),
+servers are encouraged but not required to support [OAuth dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591).
+
+For these servers, MCP Remote supports providing static OAuth client information instead.
+This is useful when connecting to OAuth servers that require pre-registered clients.
+
+Provide the client metadata as a JSON string or as a `@` prefixed filepath with the `--static-oauth-client-info` flag:
+
+```bash
+export MCP_REMOTE_CLIENT_ID=xxx
+export MCP_REMOTE_CLIENT_SECRET=yyy
+npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
+# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
+npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'
+```
+
 ### Claude Desktop
 
 [Official Docs](https://modelcontextprotocol.io/quickstart/user)
@@ -208,7 +239,7 @@ Then restarting your MCP client.
 
 ### Check your Node version
 
-Make sure that the version of Node you have installed is [18 or 
+Make sure that the version of Node you have installed is [18 or
 higher](https://modelcontextprotocol.io/quickstart/server). Claude
 Desktop will use your system version of Node, even if you have a newer
 version installed elsewhere.

src/client.ts

@@ -22,6 +22,7 @@ import {
   connectToRemoteServer,
   TransportStrategy,
 } from './lib/utils'
+import { StaticOAuthClientInformationFull, StaticOAuthClientMetadata } from './lib/types'
 import { createLazyAuthCoordinator } from './lib/coordination'
 
 /**
@@ -33,6 +34,8 @@ async function runClient(
   headers: Record<string, string>,
   transportStrategy: TransportStrategy = 'http-first',
   host: string,
+  staticOAuthClientMetadata: StaticOAuthClientMetadata,
+  staticOAuthClientInfo: StaticOAuthClientInformationFull,
 ) {
   // Set up event emitter for auth flow
   const events = new EventEmitter()
@@ -49,6 +52,8 @@ async function runClient(
     callbackPort,
     host,
     clientName: 'MCP CLI Client',
+    staticOAuthClientMetadata,
+    staticOAuthClientInfo,
   })
 
   // Create the client
@@ -154,8 +159,8 @@ async function runClient(
 
 // Parse command-line arguments and run the client
 parseCommandLineArgs(process.argv.slice(2), 'Usage: npx tsx client.ts <https://server-url> [callback-port] [--debug]')
-  .then(({ serverUrl, callbackPort, headers, transportStrategy, host, debug }) => {
-    return runClient(serverUrl, callbackPort, headers, transportStrategy, host)
+  .then(({ serverUrl, callbackPort, headers, transportStrategy, host, staticOAuthClientMetadata, staticOAuthClientInfo }) => {
+    return runClient(serverUrl, callbackPort, headers, transportStrategy, host, staticOAuthClientMetadata, staticOAuthClientInfo)
   })
   .catch((error) => {
     console.error('Fatal error:', error)

src/lib/node-oauth-client-provider.ts

@@ -6,8 +6,9 @@ import {
   OAuthTokens,
   OAuthTokensSchema,
 } from '@modelcontextprotocol/sdk/shared/auth.js'
-import type { OAuthProviderOptions } from './types'
+import type { OAuthProviderOptions, StaticOAuthClientMetadata } from './types'
 import { readJsonFile, writeJsonFile, readTextFile, writeTextFile } from './mcp-auth-config'
+import { StaticOAuthClientInformationFull } from './types'
 import { getServerUrlHash, log, debugLog, DEBUG, MCP_REMOTE_VERSION } from './utils'
 
 /**
@@ -21,6 +22,8 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
   private clientUri: string
   private softwareId: string
   private softwareVersion: string
+  private staticOAuthClientMetadata: StaticOAuthClientMetadata
+  private staticOAuthClientInfo: StaticOAuthClientInformationFull
 
   /**
    * Creates a new NodeOAuthClientProvider
@@ -33,6 +36,8 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
     this.clientUri = options.clientUri || 'https://github.com/modelcontextprotocol/mcp-cli'
     this.softwareId = options.softwareId || '2e6dc280-f3c3-4e01-99a7-8181dbd1d23d'
     this.softwareVersion = options.softwareVersion || MCP_REMOTE_VERSION
+    this.staticOAuthClientMetadata = options.staticOAuthClientMetadata
+    this.staticOAuthClientInfo = options.staticOAuthClientInfo
   }
 
   get redirectUrl(): string {
@@ -49,6 +54,7 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
       client_uri: this.clientUri,
       software_id: this.softwareId,
       software_version: this.softwareVersion,
+      ...this.staticOAuthClientMetadata,
     }
   }
 
@@ -58,6 +64,10 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
    */
   async clientInformation(): Promise<OAuthClientInformationFull | undefined> {
     if (DEBUG) await debugLog(this.serverUrlHash, 'Reading client info')
+    if (this.staticOAuthClientInfo) {
+      if (DEBUG) await debugLog(this.serverUrlHash, 'Returning static client info')
+      return this.staticOAuthClientInfo
+    }
     const clientInfo = await readJsonFile<OAuthClientInformationFull>(this.serverUrlHash, 'client_info.json', OAuthClientInformationFullSchema)
     if (DEBUG) await debugLog(this.serverUrlHash, 'Client info result:', clientInfo ? 'Found' : 'Not found')
     return clientInfo
@@ -81,16 +91,16 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
       await debugLog(this.serverUrlHash, 'Reading OAuth tokens')
       await debugLog(this.serverUrlHash, 'Token request stack trace:', new Error().stack)
     }
-    
+
     const tokens = await readJsonFile<OAuthTokens>(this.serverUrlHash, 'tokens.json', OAuthTokensSchema)
-    
+
     if (DEBUG) {
       if (tokens) {
         const expiresAt = new Date(tokens.expires_at)
         const now = new Date()
         const expiresAtTime = expiresAt.getTime()
         const timeLeft = !isNaN(expiresAtTime) ? Math.round((expiresAtTime - now.getTime()) / 1000) : 0
-        
+
         // Alert if expires_at produces an invalid date
         if (isNaN(expiresAtTime)) {
           await debugLog(this.serverUrlHash, '⚠️ WARNING: Invalid expires_at detected while reading tokens ⚠️', {
@@ -99,8 +109,8 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
             stack: new Error('Invalid expires_at timestamp').stack
           })
         }
-        
-        await debugLog(this.serverUrlHash, 'Token result:', { 
+
+        await debugLog(this.serverUrlHash, 'Token result:', {
           found: true,
           hasAccessToken: !!tokens.access_token,
           hasRefreshToken: !!tokens.refresh_token,
@@ -112,7 +122,7 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
         await debugLog(this.serverUrlHash, 'Token result: Not found')
       }
     }
-    
+
     return tokens
   }
 
@@ -126,7 +136,7 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
       const now = new Date()
       const expiresAtTime = expiresAt.getTime()
       const timeLeft = !isNaN(expiresAtTime) ? Math.round((expiresAtTime - now.getTime()) / 1000) : 0
-      
+
       // Alert if expires_at produces an invalid date
       if (isNaN(expiresAtTime)) {
         await debugLog(this.serverUrlHash, '⚠️ WARNING: Invalid expires_at detected in tokens ⚠️', {
@@ -135,15 +145,15 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
           stack: new Error('Invalid expires_at timestamp').stack
         })
       }
-      
-      await debugLog(this.serverUrlHash, 'Saving tokens', { 
+
+      await debugLog(this.serverUrlHash, 'Saving tokens', {
         hasAccessToken: !!tokens.access_token,
         hasRefreshToken: !!tokens.refresh_token,
         expiresIn: `${timeLeft} seconds`,
         expiresAt: tokens.expires_at
       })
     }
-    
+
     await writeJsonFile(this.serverUrlHash, 'tokens.json', tokens)
   }
 
@@ -153,9 +163,9 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
    */
   async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
     log(`\nPlease authorize this client by visiting:\n${authorizationUrl.toString()}\n`)
-    
+
     if (DEBUG) await debugLog(this.serverUrlHash, 'Redirecting to authorization URL', authorizationUrl.toString())
-    
+
     try {
       await open(authorizationUrl.toString())
       log('Browser opened automatically.')

src/lib/types.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events'
+import { OAuthClientInformationFull, OAuthClientMetadata } from '@modelcontextprotocol/sdk/shared/auth.js'
 
 /**
  * Options for creating an OAuth client provider
@@ -22,6 +23,10 @@ export interface OAuthProviderOptions {
   softwareId?: string
   /** Software version to use for OAuth registration */
   softwareVersion?: string
+  /** Static OAuth client metadata to override default OAuth client metadata */
+  staticOAuthClientMetadata?: StaticOAuthClientMetadata
+  /** Static OAuth client information to use instead of OAuth registration */
+  staticOAuthClientInfo?: StaticOAuthClientInformationFull
 }
 
 /**
@@ -35,3 +40,7 @@ export interface OAuthCallbackServerOptions {
   /** Event emitter to signal when auth code is received */
   events: EventEmitter
 }
+
+// optional tatic OAuth client information
+export type StaticOAuthClientMetadata = OAuthClientMetadata | null | undefined
+export type StaticOAuthClientInformationFull = OAuthClientInformationFull | null | undefined