This MCP server playground provides a TypeScript-based implementation of a Model Context Protocol (MCP) server with a Streamable HTTP transport and an OAuth proxy. It exposes an HTTP-based MCP endpoint under /mcp and includes an OAuth authorization flow (via the /oauth endpoints) and dynamic client registration through an external authorization server. The server is designed to support SSE resumability, tool execution, and session replay for stateful deployments. Tools exposed in this playground include aws-ecs for inspecting ECS resources, aws-s3 for listing S3 buckets/objects, system-time for time formatting, echo for string transformations, streaming for real-time data simulation, and project for keyword searches within the project directory. You can test MCP requests against POST /mcp, terminate sessions with DELETE /mcp, and explore OAuth metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. Use the inspector tooling described in the Getting Started section to validate MCP requests, or curl directly against the endpoints to observe behavior.

Prerequisites:

• Node.js installed (or Bun as the project package manager used in this repository)
• Git
• Access to a compatible OAuth provider (Auth0 or similar) for the proxy

Installation steps:

1. Clone the repository: git clone <repository-url> cd mcp-server-playground

2. Install dependencies (the repo uses Bun in the walkthrough, you can adapt to npm/yarn if preferred): bun install

3. Set up environment variables (copy the example and fill in values): cp .env.example .env

4. Build or prepare the server (if applicable in this project): bun run build # if there is a build step

5. Start the server in development mode: bun run dev:setup

   or run the server directly if a start script exists via node

   node dist/server.js

6. Optional: configure and run inspector or other tooling as described in the documentation: docker compose up -d bunx @modelcontextprotocol/inspector -y --config ./mcp-config.json --server mcp-server-playground-inspector

Notes and tips:

• The server relies on an OAuth proxy setup and external 3rd party authorization servers like Auth0 for token issuance and validation. Ensure your OAuth settings (domain, client ID, client secret, audience) are correctly configured in the .env file.
• SSE resumability is supported through an EventStore backend; ensure EventStore is reachable and properly configured to enable reconnect with Last-Event-ID.
• The storage layer is pluggable (Memory/Valkey) for session state. When running in a clustered deployment, distributed session state requires a shared store like Valkey.
• The endpoints expose MCP interactions and OAuth metadata. If you encounter issues with dynamic client registration, verify that the dynamic registration policy is allowed by your OAuth provider and that the proxy is correctly delegating authorization requests.
• Environment variables can be adjusted per deployment. Common variables include PORT, OAUTH_DOMAIN, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, and EVENTSTORE_URL. Review .env.example for a full list and descriptions.