MCP Server with JWT Authentication

A streamable HTTP MCP (Model Context Protocol) server with JWT authentication support for any OIDC-compliant Identity Provider.

Features

• Streamable HTTP Transport - Modern MCP transport with session management
• JWT Authentication - Secure authentication using JWKS (JSON Web Key Set) verification
• Any OIDC IdP - Works with Okta, Auth0, Keycloak, Azure AD, Google, or any OIDC-compliant provider
• Flexible Logging - Console, file, and webhook logging options

Prerequisites

• Node.js 18+
• An OIDC-compliant Identity Provider

Installation

npm install

Configuration

Copy the example environment file and configure your settings:

cp .env.example .env

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PORT | No | Server port (default: 3000) | | OIDC_ISSUER | Yes | Your IdP's issuer URL (e.g., https://your-tenant.okta.com) | | OIDC_JWKS_URI | Yes | JWKS endpoint URL for public key retrieval | | OIDC_AUDIENCE | No | Expected audience claim (typically your client ID) | | LOG_CONSOLE | No | Enable console logging (default: true) | | LOG_FILE | No | Path to log file (optional) | | LOG_WEBHOOK | No | Webhook URL for log forwarding (optional) |

IdP Configuration Examples

Okta

OIDC_ISSUER=https://your-tenant.okta.com
OIDC_JWKS_URI=https://your-tenant.okta.com/oauth2/v1/keys
OIDC_AUDIENCE=your-client-id

Auth0

OIDC_ISSUER=https://your-tenant.auth0.com/
OIDC_JWKS_URI=https://your-tenant.auth0.com/.well-known/jwks.json
OIDC_AUDIENCE=your-api-identifier

Keycloak

OIDC_ISSUER=https://keycloak.example.com/realms/your-realm
OIDC_JWKS_URI=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/certs
OIDC_AUDIENCE=your-client-id

Azure AD

OIDC_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0
OIDC_JWKS_URI=https://login.microsoftonline.com/your-tenant-id/discovery/v2.0/keys
OIDC_AUDIENCE=your-client-id

Usage

Development

npm run dev

Production

npm run build
npm start

API Endpoints

| Method | Endpoint | Auth | Description | |--------|----------|------|-------------| | POST | /mcp | Yes | MCP request handler | | GET | /mcp | Yes | SSE stream for notifications | | DELETE | /mcp | Yes | Close session | | GET | /health | No | Health check |

Authentication

All /mcp endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

The server validates tokens by:

1. Fetching public keys from the configured JWKS endpoint
2. Verifying the token signature
3. Validating the issuer claim matches OIDC_ISSUER
4. Optionally validating the audience claim if OIDC_AUDIENCE is set

MCP Resources

The server includes example MCP components:

• Tool: greet - Greets a person by name
• Prompt: greeting - A greeting prompt template
• Resource: config://app - Application configuration resource

License

ISC