This MCP server implements a stateless version of the Streamable HTTP transport with OAuth support. It acts as a remote MCP server that can be plugged into MCP hosts and clients to enable streamable HTTP for MCP, guarded by OAuth tokens. The included express app coordinates the Streamable HTTP transport, SSE transport, and OAuth flow by proxying to an upstream OAuth server (e.g., Auth0) and issuing its own access tokens for clients to use when communicating with the MCP server. You can run the stateless variant for serverless-like deployments or the stateful variant for scenarios requiring in-memory or Redis-backed session management. To start, run the stateless server with Bun as shown in the installation guide. Once running, you can configure MCP clients to connect to the server using the provided OAuth endpoints, and then engage the Streamable HTTP transport to send MCP messages and manage subscriptions over HTTP/1.1 with Server-Sent Events (SSE) fallbacks when appropriate.

Prerequisites:

• Bun (preferred runtime) installed on your system
• Git to clone the repository
• An OAuth provider setup (e.g., Auth0) with a registered client and dynamic client registration enabled

Steps:

1. Clone the repository git clone https://github.com/NapthaAI/napthaai-http-oauth-mcp-server.git cd napthaai-http-oauth-mcp-server

2. Install dependencies (Bun handles JS/TS projects; no separate npm install required if Bun is used): bun install

3. Prepare environment

   • Copy the environment template and fill in values: cp .env.template .env

     Edit .env with your AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, etc.

4. Run the stateless server (streamable HTTP transport only): bun run src/app.stateless.ts

5. Optional: Run the stateful server (both SSE and streamable HTTP transports with state): bun run src/app.stateful.ts

Note: The project recommends Bun as the runtime for best compatibility. If you must use npm, you may run equivalent commands via npm scripts if provided, but Bun is the officially recommended path for this repository.

Tips and caveats:

• OAuth setup: You must configure an OAuth provider (Auth0 is recommended) and fill the resulting credentials into the .env file. Dynamic Client Registration (RFC 7591) is needed for MCP clients to register without manual UI steps.
• Environment variables: Ensure AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, and the appropriate audience or API identifier are set. The PORT can be adjusted if you already have a service running on the default port.
• Transport choices: Use the stateless variant for serverless or highly scalable deployments; use the stateful variant when you need in-memory or Redis-backed session persistence.
• Security: The server proxies tokens to avoid leaking end-user tokens directly to MCP clients. Ensure your upstream OAuth server is properly secured and that redirect URIs and allowed origins are configured according to your deployment needs.
• Debugging: If the server fails to start, check that Bun is installed and that the environment variables are correctly defined. Review logs for OAuth negotiation issues or dynamic client registration problems.