MCP Server Boilerplate

by chrisleekr

Not rated
GitHub

About

A TypeScript boilerplate for building MCP servers with streamable HTTP and OAuth proxy support.

Details

Author
chrisleekr
Categories
Developer Tools

Setup

Install MCP Server Boilerplate in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/chrisleekr/mcp-server-boilerplate

Follow the installation instructions in the repository README, then restart your MCP client.

A playground for Model Context Protocol (MCP) server built with TypeScript and Streamable HTTP transport with an OAuth Proxy for 3rd party authorization servers like Auth0.

- MCP 2025-06-18 Compliant: Full compliance with the latest MCP specification including SSE resumability, tool annotations, and structured content.
- MCP Server implementation: HTTP-Based Streamable transport using@modelcontextprotocol/sdkwith HTTP transport, session management, and tool execution.
- SSE Resumability: Clients can reconnect withLast-Event-IDheader to resume receiving events after connection breaks, powered by EventStore.
- OAuth authentication/3rd party authorization: Implements an OAuth server for MCP clients with RFC 8707 Resource Indicators and RFC 9728 authorization discovery, delegating to Auth0.
- Storage: Pluggable storage abstraction (Memory/Valkey) with EventStore for SSE event persistence and replay.
- Session Management: Support stateful sessions by using replay of initial request for distributed deployments.
- Security: Strict Origin validation to prevent DNS rebinding attacks, WWW-Authenticate headers for authorization discovery.
- Tools:

- aws-ecs: Investigate the ECS service, task and cloudwatch logs using AWS ECS, Cloudwatch Logs and Bedrock
- aws-s3: Get the list of S3 buckets and objects
- system-time: Get the current system time in various formats with timezone support
- echo: Echo a message back with transformations, repetition
- streaming: Simulate real-time streaming data with live updates
- project: Find keywords in the current project directory

- echo://documentation: Documentation for the echo tool (static resource)
- echo://result/{resultId}: Access echo operation results (resource template)

- Architecture Overview- System design, data flows, and diagrams
-
Environment Variables- Configuration options
- Tool Documentation(in each tool directory):

- echo- Message echo with transformations
-
system-time- Current time with timezone support
-
streaming- Real-time data streaming simulation
-
project- Keyword search in project files
-
aws-ecs- ECS investigation with AI analysis
-
aws-s3- S3 bucket and object listing

- The Model Context Protocol specrequires Dynamic Application Registrationbecause it provides a standardized way for MCP clients to automatically register with new servers and obtain OAuth client IDs without user interaction. The main reason for this mechanism is because MCP clients can't know all possible services in advance and manual registration would create significant effort for users and it is not scalable. If do not support Dynamic Application Registration, then MCP clients need to provide OAuth client ID and secret to the server, which is not secure and not scalable.
- However, enabling Dynamic Application Registration (if supported) becomes a
security riskbecause the endpoint is a public endpoint that anyone can create OAuth clients. It can easily be abused, such as by flooding with unwanted client registrations. Hence, Auth0 has disabled Dynamic Application Registration
- As a result, this project provides a way to enable Dynamic Application Registration for MCP server by using OAuth Proxy, but delegating authorization to 3rd party authorization server like Auth0, Github, Google, etc.

git clone <your-repo> cd mcp-server-playground
curl -fsSL https://bun.sh/install | bash

Set up the MCP server for local development

helm repo add chrisleekr https://chrisleekr.github.io/helm-charts/ helm repo update helm install mcp-server-playground chrisleekr/mcp-server-playground

-

Create MCP configuration file for local build

Create a.cursor/mcp.jsonfile in your project directory (for project-specific setup) or~/.cursor/mcp.jsonin your home directory (for global setup):

{ "mcpServers": { "mcp-server-playground-cursor": { "type": "http", "url": "http://localhost:3000/mcp" } } }

-

Copymcp-config.example.jsontomcp-config.json

Editmcp-config.jsonto point to the correct MCP server

docker compose up -d # Then run the inspector bunx @modelcontextprotocol/inspector -y --config ./mcp-config.json --server mcp-server-playground-inspector
docker compose up -d bun run test:inspector

- Go toAuth0 Dashboard
- Click on "Applications"
- Click on "Create Application"

- Name: MCP Server Playground
- Application Type: Regular Web Application

- Click on "Settings"
- Set the following settings:

- Allowed Callback URLs:http://localhost:3000/oauth/auth0-callback
- Allowed Web Origins:http://localhost:3000

- Click on "APIs"
- Click on "Create API"

- Name: MCP Server Playground
- Identifier:urn:mcp-server-playground
- JSON Web Token (JWT) Profile: Auth0
- JSON Web Token (JWT) Signature Algorithm: RS256

How to make stateful session with multiple MCP Server instances?

When the MCP server is deployed as a cluster, it is not possible to make it stateful with multiple MCP Server instances because the transport is not shared between instances by design.

To make it truly stateful, I used Valkey to store the session id with the initial request.

When the request comes in to alternative MCP server instance, it will check if the session id is in the Valkey. If it is, it will replay the initial request and connect the transport to the server.

Inspired fromhttps://github.com/modelcontextprotocol/modelcontextprotocol/discussions/102

SeeArchitecture - Stateful Session Managementfor the detailed sequence diagram.

- Streaming is not working as expected. It returns the final result instead of streaming the data.

- Authorization
-
Dynamic Application Registration
-
Let's fix OAuth in MCP
-
OAuth for MCP explained with a real-world example
-
Treat the MCP server as an OAuth resource server rather than an authorization server
-
HTTP + SSE MCP Server w/ OAuth by @NapthaAI

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

Local stdio MCP server that lets AI coding agents read and maintain structured architecture, rules, and decisions directly from your repository.

Official Context7 MCP server that brings up-to-date, version-specific library documentation and code examples into AI coding prompts.

Remote, no-auth MCP server providing AI-powered codebase context and answers

Instead of direct calling MCP tools, mcpcode server transforms MCP tool calls into TypeScript programs, enabling smarter, lower-latency orchestration by LLMs.

Help agents automatically write and test stories for your UI components

Official Svelte MCP server, provides docs and suggestions on the generated code.

Supercharge your Agent with Semantic Code Intelligence and save 💰 in the process!

Execute any LLM-generated code in the YepCode secure and scalable sandbox environment and create your own MCP tools using JavaScript or Python, with full support for NPM and PyPI packages

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.