MCP OAuth Token Manager

Build a simple OAuth token manager for Model Context Protocol (MCP) servers that handles token storage, validation, and refresh operations.

Requirements

Create a token management system with the following features:

1. Token Storage: Store and retrieve OAuth tokens for different MCP servers by name
2. Token Validation: Check if a stored token is still valid based on its expiration time
3. Token Refresh: Automatically refresh expired tokens using refresh tokens
4. Multiple Servers: Support managing tokens for multiple MCP servers independently

Your implementation should:

• Store tokens securely with all necessary OAuth information (access token, refresh token, expiration time, token type, scope)
• Validate tokens before use, accounting for a configurable time buffer before actual expiration
• Attempt to refresh tokens when they are expired or about to expire
• Support listing all servers that have stored tokens
• Handle token cleanup (removal of specific tokens or all tokens)

Test Cases

• When storing a token for "server-1", it can be retrieved by the same server name @test
• When checking if a token is valid, it returns false if the token expiration is in the past @test
• When getting a valid token for a server with an expired token, it attempts to refresh the token using the refresh token @test
• When listing servers, it returns all server names that have stored tokens @test

@generates

API

/**
 * Token management for MCP OAuth servers
 */
export class MCPTokenManager {
  constructor(validationBufferSeconds?: number);

  /**
   * Store a token for a server
   */
  storeToken(serverName: string, token: TokenData): Promise<void>;

  /**
   * Get a token for a server
   */
  getToken(serverName: string): Promise<TokenData | null>;

  /**
   * Get a valid token, refreshing if necessary
   */
  getValidToken(serverName: string, refreshCallback: (refreshToken: string) => Promise<TokenData>): Promise<string | null>;

  /**
   * Check if a token is valid
   */
  isTokenValid(token: TokenData): boolean;

  /**
   * List all servers with stored tokens
   */
  listServers(): Promise<string[]>;

  /**
   * Delete a token for a server
   */
  deleteToken(serverName: string): Promise<void>;

  /**
   * Clear all stored tokens
   */
  clearAll(): Promise<void>;
}

export interface TokenData {
  accessToken: string;
  tokenType: string;
  expiresAt?: number;
  refreshToken?: string;
  scope?: string;
}

Dependencies { .dependencies }

@google/gemini-cli-core { .dependency }

Provides MCP OAuth integration and token management capabilities.