@enconvo/mcp-oauth

OAuth authentication utilities for MCP (Model Context Protocol) clients, providing secure authentication flows for connecting to OAuth-protected MCP servers.

Features

• Complete OAuth 2.0 Flow: Implements authorization code flow with PKCE for enhanced security
• Secure Token Management: Encrypted storage and automatic refresh of OAuth tokens
• Dynamic Port Allocation: Automatically finds available ports for OAuth callback servers
• Browser Integration: Seamlessly opens authorization URLs in the user's default browser
• MCP Integration: Purpose-built for Model Context Protocol servers with OAuth support
• Error Recovery: Graceful handling of authentication failures and connection issues

Installation

npm install @enconvo/mcp-oauth @modelcontextprotocol/sdk

pnpm add @enconvo/mcp-oauth @modelcontextprotocol/sdk

Usage

Basic OAuth Flow

import { OAuthFlowManager } from '@enconvo/mcp-oauth';

const flowManager = new OAuthFlowManager(
  'https://api.example.com/mcp', // MCP server URL
  'my-mcp-client'                // Client name
);

try {
  const tools = await flowManager.executeOAuthFlow();
  console.log('Available tools:', tools);
} catch (error) {
  console.error('Authentication failed:', error);
}

Custom OAuth Client Provider

import { SimpleOAuthClientProvider } from '@enconvo/mcp-oauth';
import { OAuthClientMetadata } from '@modelcontextprotocol/sdk/shared/auth.js';

const clientMetadata: OAuthClientMetadata = {
  client_name: 'my-app',
  redirect_uris: ['http://localhost:8080/callback'],
  grant_types: ['authorization_code', 'refresh_token'],
  response_types: ['code'],
  token_endpoint_auth_method: 'client_secret_post',
  scope: 'mcp:tools'
};

const provider = new SimpleOAuthClientProvider(
  'http://localhost:8080/callback',
  clientMetadata
);

Port Management

import { findAvailablePort, isPortAvailable } from '@enconvo/mcp-oauth';

// Check if a specific port is available
const available = await isPortAvailable(8080);

// Find the next available port starting from 8080
const port = await findAvailablePort(8080);
console.log(`Using port: ${port}`);

Requirements

• Node.js >= 18.0.0
• @modelcontextprotocol/sdk >= 1.17.3
• @enconvo/api (peer dependency, optional for non-Enconvo environments)

API Reference

OAuthFlowManager

Main class for managing OAuth authentication flows with MCP servers.

Constructor

new OAuthFlowManager(serverUrl: string, clientName: string)

Methods

• executeOAuthFlow(): Promise<any> - Execute complete OAuth flow and return MCP tools list

SimpleOAuthClientProvider

OAuth client provider implementation with secure token storage.

Constructor

new SimpleOAuthClientProvider(redirectUrl: string | URL, clientMetadata: OAuthClientMetadata)

Methods

• clientInformation(): Promise<OAuthClientInformation | undefined>
• saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>
• tokens(): Promise<OAuthTokens | undefined>
• saveTokens(tokens: OAuthTokens): Promise<void>

Port Utilities

• isPortAvailable(port: number): Promise<boolean> - Check if a port is available
• findAvailablePort(startPort: number, maxAttempts?: number): Promise<number> - Find next available port

Security Features

1. PKCE Support: Uses Proof Key for Code Exchange for enhanced security
2. Encrypted Storage: All OAuth tokens and credentials are encrypted
3. Localhost Only: Callback servers use localhost-only URLs
4. Automatic Cleanup: Temporary servers are automatically closed after use
5. Timeout Protection: 5-minute timeout for OAuth authorization flows

License

MIT © Enconvo

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

• GitHub Issues: Report bugs and feature requests
• Documentation: MCP Protocol Documentation