oauth 2.0 authorization server with pkce support
Implements a complete OAuth 2.0 authorization server with PKCE (Proof Key for Code Exchange) support following the recommended separate auth server architectural pattern. The AuthModule (src/modules/auth/index.ts) handles /authorize, /token, /register, /introspect, and /revoke endpoints, enabling secure token-based authentication for MCP clients. Supports both internal (in-process) and external (remote) token validation modes, allowing flexible deployment architectures from development to production horizontal scaling.
Unique: Implements OAuth as a separate architectural module (AuthModule) that can run in-process or remotely, with explicit token validator abstraction (InternalTokenValidator vs ExternalTokenValidator) enabling zero-downtime auth server upgrades and horizontal scaling via Redis-backed session storage without coupling auth logic to MCP protocol implementation.
vs alternatives: Decouples authentication from MCP protocol handling (unlike monolithic implementations), enabling independent scaling and security updates while supporting both development convenience (internal mode) and production isolation (external mode).
stateful mcp protocol server with multi-transport support
Implements a complete Model Context Protocol server (MCPModule at src/modules/mcp/index.ts) exposing 100+ resources and 9 tools across multiple transport layers: Streamable HTTP (/mcp endpoint) and legacy Server-Sent Events (/sse endpoint). The server maintains session state per authenticated client and implements the full MCP feature set including tools, resources, prompts, sampling, completions, and logging. Transport abstraction allows clients to choose between modern streaming HTTP and legacy SSE based on network constraints or client capabilities.
Unique: Implements dual-transport MCP server with explicit transport abstraction layer supporting both modern Streamable HTTP and legacy SSE, enabling backward compatibility while demonstrating production patterns like per-session state management, 100+ resource definitions, and 9 tool implementations in a single reference server.
vs alternatives: More comprehensive than minimal MCP examples (includes full protocol feature set, 13 example apps, and production patterns), yet more focused than general-purpose LLM frameworks by specializing entirely on MCP protocol reference implementation.
legacy server-sent events (sse) transport for backward compatibility
Maintains legacy Server-Sent Events (SSE) transport at /sse endpoint for backward compatibility with older MCP clients and constrained environments. SSE uses HTTP long-polling with text/event-stream MIME type, enabling unidirectional server-to-client streaming without WebSocket support. While less efficient than Streamable HTTP, SSE provides broader compatibility with legacy proxies, firewalls, and client libraries that may not support modern streaming transports.
Unique: Maintains legacy SSE transport alongside modern Streamable HTTP, enabling backward compatibility with older clients while demonstrating transport abstraction patterns that allow independent evolution of transport layers without affecting MCP protocol implementation.
vs alternatives: Provides broader compatibility than Streamable HTTP alone; less efficient than modern transports but more compatible with restrictive network environments.
interactive web ui for mcp protocol exploration and testing
Provides a browser-based interactive UI (src/static/index.html, styles.css) enabling users to explore MCP server capabilities, authenticate via OAuth, and test tools/resources without writing code. The UI displays available tools with their schemas, resources with metadata, and prompts with argument templates. Users can invoke tools, retrieve resources, and sample prompts directly from the browser, with real-time response display and error handling. The UI serves as both a learning tool and a testing interface for MCP server development.
Unique: Provides browser-based interactive UI with OAuth integration, real-time tool/resource/prompt discovery, and direct invocation capabilities, enabling non-developers to explore MCP server capabilities while serving as a testing and learning interface for developers.
vs alternatives: More accessible than CLI tools or code-based testing; more focused than general-purpose API explorers by specializing on MCP protocol patterns.
13 example mcp applications with interactive ui integration
Provides 13 stateless MCP App example servers (ExampleAppsModule at src/modules/example-apps/index.ts) each exposing domain-specific tools and resources via individual /:slug/mcp endpoints (e.g., /budget-allocator/mcp). Each example app demonstrates interactive UI patterns for MCP integration, showing how to build practical applications on top of the MCP protocol. Apps are stateless and independently deployable, serving as both learning resources and copy-paste templates for builders.
Unique: Bundles 13 complete, runnable MCP application examples within a single reference server, each with independent /:slug/mcp endpoints and interactive UI demonstrations, enabling copy-paste learning and rapid prototyping without requiring separate repository clones or complex setup.
vs alternatives: Provides more comprehensive example coverage than typical single-example reference implementations, with interactive UI patterns and stateless architecture enabling easy extension and deployment.
redis-backed session management for horizontal scalability
Implements session persistence via Redis integration enabling the MCP server to scale horizontally across multiple instances without losing client session state. Session data (authentication tokens, tool invocation history, resource access logs) is stored in Redis with configurable TTL, allowing any instance in a load-balanced cluster to serve subsequent requests from the same client. The session manager abstracts Redis operations, supporting both in-memory fallback (development) and Redis backend (production).
Unique: Abstracts session storage behind a configurable backend interface supporting both in-memory (development) and Redis (production) implementations, with automatic fallback and TTL-based expiration, enabling seamless transition from single-instance to horizontally-scaled deployments without code changes.
vs alternatives: Provides explicit session abstraction layer (vs embedding Redis calls throughout codebase), enabling easy testing, local development without Redis, and future migration to alternative backends (DynamoDB, Memcached) without refactoring.
three operational modes (internal, external, demo) with flexible authentication
Supports three distinct operational modes controlled by AUTH_MODE environment variable: (1) internal mode runs AuthModule in-process with InternalTokenValidator for development convenience, (2) external mode delegates token validation to a remote auth server via ExternalTokenValidator for production isolation, (3) demo mode disables authentication entirely for public demonstrations. Mode selection is determined at startup via config.auth.mode, allowing the same codebase to run in development, production, and demo environments without code changes.
Unique: Implements three distinct operational modes via explicit TokenValidator abstraction (InternalTokenValidator, ExternalTokenValidator, DemoTokenValidator) determined at startup, enabling the same codebase to serve development (in-process auth), production (remote auth), and demo (no auth) use cases without conditional logic scattered throughout the application.
vs alternatives: Cleaner than feature-flag-based mode selection by using polymorphic validator implementations, reducing cognitive load and enabling easier testing of each mode independently.
mcp tool invocation with 9 reference implementations
Implements 9 reference tools demonstrating various MCP tool patterns including parameter validation, async execution, error handling, and result formatting. Tools are registered in the MCP protocol module with JSON schema definitions enabling clients to discover tool signatures and invoke them with type-safe parameters. Each tool implementation demonstrates best practices for error handling, logging, and result serialization, serving as templates for custom tool development.
Unique: Provides 9 complete tool implementations with JSON schema definitions, async execution patterns, and error handling demonstrations, enabling clients to discover tool signatures via MCP protocol and invoke them with type-safe parameters while serving as copy-paste templates for custom tool development.
vs alternatives: More comprehensive than minimal tool examples by including schema definitions, async patterns, and error handling; more focused than general-purpose agent frameworks by specializing on MCP tool protocol patterns.
+4 more capabilities