mcp-client-auth

MCP Client Auth is a TypeScript library that provides OAuth2 authentication utilities tailored for MCP client implementations. It streamlines the standard OAuth2 authorization code flow with PKCE, automatic server metadata discovery, and optional dynamic client registration, so you can add OAuth support to MCP clients with minimal boilerplate. The library exposes a high-level McpClient that handles authentication, token management, and tool access, as well as a lower-level McpOAuth class for custom integration or advanced flows. You can rely on automatic token storage (via a pluggable OAuthStore) and an HTTP client powered by Ky for authenticated requests.

To use it, instantiate McpClient with the MCP server URL and optional OAuth store. You can then check whether authentication is required with isAuthRequired(), which returns an AuthStatus indicating if a redirect to an OAuth provider is necessary. If authentication is required, you can retrieve the authorization URL from the AuthorizationRequest and direct the user there. After the user authorizes, handleAuthByCode exchanges the authorization code for tokens and persists them via your store. Once authenticated, you can use the client to list tools and call tools exposed by the MCP server, all while the library automatically manages token refreshing and secure storage. For advanced use cases or custom auth logic, you can work directly with McpOAuth to generate authorization requests, exchange codes, and obtain a Ky HTTP client for making authenticated requests.

Prerequisites:

• Node.js (14+ recommended) and npm/yarn installed
• Basic TypeScript tooling is optional but helpful for development

Installation steps:

1. Install the library from npm:

npm install mcp-client-auth

2. If you plan to develop TypeScript apps using the types, ensure your tsconfig is set up and you have @types/node if needed:

# optional, for TS projects
npm install --save-dev typescript @types/node

3. Basic usage in a Node/TypeScript project:

import { McpClient } from 'mcp-client-auth';

const client = new McpClient({
  url: 'https://mcp.example.com',
  oauthRedirectUri: 'http://localhost:3000/mcp/oauth/callback',
  // store: your OAuthStore implementation (optional)
});

4. Run or bundle your app as you normally would in your environment (Node.js, bundlers, etc.).

• The library focuses on MCP client authentication; it automatically discovers server metadata and can perform dynamic client registration where supported.
• If you provide a custom OAuth store, tokens will be saved and reused across sessions; ensure your store implements load/save/clear as documented.
• When using the High-Level McpClient, you typically only need to call isAuthRequired() and, if needed, handleAuthByCode(...) after the OAuth flow completes.
• For environments with restricted network access, ensure the discovery endpoint /.well-known/oauth-authorization-server is reachable and that PKCE flows are supported by the OAuth provider.
• The default OAuth flow uses PKCE; you can customize redirect URIs and server URLs through McpClientOptions or McpOAuthOptions as needed.