example-remote-server

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.

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.

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.

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.

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.

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).

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.

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.

Exposes 100+ reference resources via the MCP protocol with hierarchical organization, metadata, and content retrieval. Resources are registered with URI schemes, MIME types, and descriptions enabling clients to discover and retrieve resource content. The resource system demonstrates patterns for exposing static content, generated content, and external data sources through a unified MCP interface. Resources support filtering and pagination for large collections.

Implements MCP prompt templates enabling clients to discover and instantiate reusable prompt patterns with variable substitution. The prompt system supports sampling (generating multiple completions from a single prompt) and completion (generating single responses), with configurable parameters for model selection, temperature, and token limits. Prompts are registered with argument schemas enabling clients to discover required variables and invoke prompts with type-safe parameters.

Implements structured logging and event notification system capturing all MCP protocol interactions, authentication events, tool invocations, and resource access. Logs are structured as JSON enabling programmatic analysis and integration with observability platforms (ELK, Datadog, etc.). The notification system enables clients to subscribe to server events (tool execution, resource access, authentication) via MCP protocol, supporting real-time monitoring and audit trails.

Implements modern Streamable HTTP transport for MCP protocol using HTTP/1.1 chunked transfer encoding, enabling efficient streaming of large responses (tool results, resource content, completions) without buffering entire payloads in memory. The transport layer abstracts HTTP details from the MCP protocol implementation, supporting both request/response streaming and server-initiated notifications. Streamable HTTP is the recommended transport for new implementations, offering lower latency and better resource efficiency than legacy SSE.