oauth-callback

oauth-callback is a lightweight MCP-enabled OAuth 2.0 callback handler that can run as a Node.js-based server. It provides a secure, localhost-only endpoint to capture OAuth authorization codes and integrates with the MCP SDK to act as an OAuth provider within MCP-enabled applications. The library supports multiple runtimes (Node.js, Deno, Bun) and offers flexible token storage (in-memory or file-based), customizable HTML templates for success and error pages, and robust error handling. To use it within an MCP workflow, instantiate or import the MCP-compatible provider from oauth-callback/mcp and connect a client via a transport that uses the provider to obtain and refresh tokens. This enables MCP-enabled applications to perform OAuth flows without exposing tokens to external services, while still benefiting from MCP’s standardized protocol for device and app contexts.

Prerequisites:

• Node.js 18+ (or compatible runtime like Deno or Bun if you plan to use the multi-runtime features)
• npm or bun (depending on your preferred package manager)

Install the package:

• npm: npm install oauth-callback open

• bun: bun add oauth-callback open

Note: The open package is optional but recommended for browser launching during the OAuth flow. If you plan to use pnpm, install it explicitly as: pnpm add open

Basic usage (example):

1. Install dependencies in your project (as shown above).
2. Import and use the library in your application to start an OAuth flow and handle the callback.
3. If integrating with MCP, import from oauth-callback/mcp and configure your MCP provider as shown in the repository documentation.

Tips and common considerations:

• The library supports in-memory and file-based token storage. Use fileStore() for persistence across sessions. If you prefer ephemeral sessions, use inMemoryStore().
• When deploying locally, bind to localhost and use a known redirect/callback URL (e.g., http://localhost:3000/callback) to avoid mixed content issues.
• The MCP integration examples show how to create a browserAuth provider and connect with an MCP Client using a transport that includes an authProvider. This makes it straightforward to incorporate OAuth flows into MCP-powered applications.
• If you customize the HTML templates for success or error pages, ensure you escape dynamic content properly and consider accessibility (focus management, readable contrast).
• For production, consider configuring timeout, port, and hostname explicitly to align with your deployment environment. Abort signals and cancellation support are available for programmatic control.