MCP Server Playground

This MCP Server Playground provides an HTTP-based Model Context Protocol server with an OAuth proxy to enable third-party authorization, SSE event streaming, and pluggable storage for testing and developing MCP clients in a safe, isolated environment.

How to use

You interact with the MCP server by sending MCP protocol requests through the HTTP endpoint and by testing client registration, authorization, and SSE streaming. The server supports resumable server-sent events, so you can reconnect with a last event id to resume receiving updates. Authentication is delegated to a third-party authorization server via an OAuth proxy, allowing you to test real-world authorization flows with providers like Auth0, Github, or Google.

To test the MCP client workflow, start by routing your MCP client requests to the server’s mcp endpoint and use the well-known OAuth metadata endpoints to discover authorization behavior. You can also exercise session management and replay features to ensure continuity in distributed deployments.

How to install

Prerequisites: you need Node-like tooling to run the server locally, plus access to a container or browser to simulate client actions.

1. Clone the repository and enter the project directory.

2. Install Bun if it is not already installed.

curl -fsSL https://bun.sh/install | bash

3. Install dependencies with Bun.

bun install

4. Create a local environment configuration by copying the example.

cp .env.example .env

5. Set up the MCP server for local development.

bun run dev:setup

6. If you want to run the deployment in a containerized environment, you can explore the Helm chart for Kubernetes installations.

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

Additional configuration and architecture notes

Key components include a 2025 MCP compliant server with SSE resumability, an OAuth proxy for third-party authorization, and a pluggable storage backend with EventStore for event replay. Stateful session management is achieved by replaying the initial request when needed for distributed deployments.

Security considerations emphasize strict origin validation to prevent DNS rebinding attacks, with WWW-Authenticate headers for authorization discovery.

If you deploy multiple MCP servers, you can enable stateful behavior by leveraging a shared session store (Valkey) to persist the initial session and replay it on subsequent connections. This helps coordinate transport across instances in a cluster.

Endpoints

The server exposes endpoints to manage MCP requests, OAuth metadata, and authorization flows. These include health checks, MCP request handling, session termination, OAuth metadata discovery, client registration, and token management.

Stateful sessions with multiple MCP servers

When running as a cluster, you can achieve true statefulness by storing the initial session information in a persistent store (such as Valkey). If a request arrives at a different server, the system replays the initial request against the shared session to continue the transport connection seamlessly.

Stateful session references and tools you can use

The project provides tools to inspect and drive various aspects of MCP testing, including time utilities and streaming simulations.

Security and troubleshooting notes

If you encounter streaming not behaving as expected, verify that the server is reachable at the mcp endpoint, ensure session replay is configured correctly, and confirm that the OAuth proxy is correctly delegating authorization to your third-party provider.

Available tools

aws-ecs

Investigate ECS services, tasks, and CloudWatch logs for debugging and monitoring.

aws-s3

List S3 buckets and objects to verify storage and access patterns.

system-time

Get the current system time in multiple formats with timezone support.

echo

Echo a message back with optional transformations.

streaming

Simulate real-time streaming data with live updates.

project

Find keywords in the current project directory to aid navigation.