@civic/hub-bridge v0.2.3

Hub Bridge

A CLI tool that bridges stdio-based Model Context Protocol (MCP) clients with HTTP/SSE-based MCP servers, while handling authentication.

Overview

Hub Bridge connects local MCP clients (such as Claude Desktop) using stdio transport with remote MCP servers using HTTP/SSE transport. It handles authentication flows for both the Civic identity service and third-party services that require OAuth.

Easy Installation for Claude Desktop

The hub bridge provides a convenient installer command that automatically configures Claude Desktop to use Civic's MCP servers:

npx @civic/hub-bridge install claude-desktop

Then just start Claude Desktop.

Requirements

• Node.js >= 18.0.0

Architecture

The Hub Bridge follows a modular architecture with clear separation of concerns:

Core Components

1. Bridge (bridge.ts)

   • Core functionality that connects stdio and SSE transports
   • Manages message forwarding between client and server
   • Handles service-specific authentication flows

2. Auth Provider (authProvider.ts)

   • Implements the OAuth client interface for Civic authentication
   • Manages PKCE flow and token storage
   • Provides client information to the server

3. Callback Server (callbackServer.ts)

   • Creates a local HTTP server to receive OAuth redirects
   • Implements dynamic port selection to avoid conflicts
   • Handles token exchange after authorization

4. Token Store (tokenStore.ts)

   • Manages secure storage of authentication tokens
   • Provides methods for storing and retrieving different token types
   • Handles file system operations for persistence

5. OIDC Configuration (oidc.ts)

   • Fetches OpenID Connect configuration from discovery endpoints
   • Provides fallback values if discovery fails
   • Caches configuration for improved performance

6. Configuration (config.ts)

   • Centralizes all configuration values
   • Loads environment variables with sensible defaults
   • Defines client and server information

7. Type Definitions (types.ts)

   • Contains shared type definitions and interfaces
   • Includes helpers for type checking

Authentication Flow

1. Civic Authentication

   • Automatically initiated when the bridge starts
   • Uses PKCE (Proof Key for Code Exchange) for enhanced security
   • Discovers the authorization endpoint using OpenID Connect discovery
   • Opens a browser window to the correct Civic auth URL during first startup
   • Stores tokens locally for subsequent uses
   • The MCP SDK proactively attempts authentication at startup rather than waiting for the first request
   • The bridge overrides the default SDK behavior to use the correct auth server URL

2. Service-Specific Authentication

   • Intercepts auth URL errors from the server
   • Opens browser for user authorization
   • Manages callback and token exchange
   • Continues the original request after authentication

Usage

Installation for Claude Desktop

For the easiest setup with Claude Desktop:

npx @civic/hub-bridge install claude-desktop

Then launch Claude Desktop and select "Civic" from the list of MCP providers in settings.

Available Install Targets

The hub bridge supports automatic installation for:

• claude-desktop - Configures Claude Desktop (macOS only)
• claude-code - Configures Claude Code (CLI tool)

Environment Variables

• MCP_REMOTE_URL: URL of the remote MCP server (default: 'https://ai.civic.com/hub/mcp')
• CIVIC_AUTH_URL: URL of the Civic auth service (default: 'https://auth.civic.com/oauth')
• CIVIC_AUTH_CLIENT_ID: OAuth client ID for authentication
• NO_LOGIN: When set to 'true', bypasses the authentication process and uses a public configuration. With this option enabled, you will not be asked to login when using the Civic MCP hub, but will instead access a limited set of servers available to the public.
• NO_AUTH_CAPTURE: When set to 'true', disables third-party service authorization prompts. The bridge will not attempt to open authorization URLs in the browser when services require authentication.
• CALLBACK_PORT: Port for the OAuth callback server (default: 8976)

Development

1. Install dependencies: pnpm install
2. Build the project: pnpm build
3. Run in development mode: pnpm dev

Environment Configuration

The logger can be configured through environment variables:

• LOG_LEVEL: Set the log level (error, warn, info, debug, trace)
• DEBUG=true: Shorthand to set log level to DEBUG
• LOG_TIMESTAMPS=true: Include ISO timestamps in log output
• MASK_SENSITIVE_DATA=false: Disable sensitive data masking (not recommended for production)

Example:

LOG_LEVEL=debug LOG_TIMESTAMPS=true node dist/index.js