MCP Playground Logo

MCP Playground

An Open-Source Web-Based Tool for Testing and Inspecting MCP Servers

What is MCP Playground?

MCP Playground is a web-based developer tool designed to inspect and test Model Context Protocol (MCP) servers. It provides an interactive environment for exploring tools, resources, and prompts exposed by MCP servers, making it easy to debug and develop MCP integrations.

Key Features:

🌐 Web-Based Interface - No CLI required, test MCP servers directly from your browser
🔌 HTTP Transport Support - Works with HTTP-based and supports stateless MCP interactions
🔧 Interactive Testing - Execute tools, view resources, and test prompts in real-time
📊 Request Logging - Track all JSON-RPC requests and responses for debugging
🔒 OAuth Integration - Secure OAuth flows for MCP servers that require authentication
🛡️ Application Encryption - AES-256-GCM protects OAuth tokens and client secrets
👥 Flexible Authentication - Use anonymously without signing in, or create an account (GitHub OAuth, Magic Link) for persistent data and cross-device access

Why MCP Playground?

MCP Playground was built out of a need for a quick, easy way to inspect and test MCP servers without dealing with complex CLI setups or writing custom scripts every time. When developing with MCP, there was a clear need for a simple web interface to:

Quickly connect to any MCP server and see what it exposes
Test tools and prompts interactively without writing code
Debug OAuth flows when integrating with authenticated servers
View request/response logs to understand what's happening under the hood
Switch between servers easily while working on multiple projects

Instead of rebuilding these capabilities for each project, this tool was made open source so anyone working with MCP can benefit from it. It's the tool that should exist for anyone working with Model Context Protocol.

Tech Stack

MCP Playground is built with modern and reliable technologies:

Frontend: Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4, Shadcn UI
Backend: tRPC, Node.js, Drizzle ORM
Database: PostgreSQL 17
Authentication: Better Auth (GitHub OAuth, Magic Link, Anonymous)
Email: React Email with Resend
MCP Integration: @modelcontextprotocol/sdk
Code Quality: Ultracite (AI-ready linter), Biome

Getting Started

Prerequisites

Required Versions:

Node.js (v18 or higher)
pnpm (v10 or higher)
Docker (v20 or higher)

Before running the application, you'll need to set up services and configure environment variables. For more details on environment variables, see the Environment Variables section.

Quick Start Guide

Clone and Install

# Clone the repository
git clone https://github.com/yourusername/mcp-playground.git
cd mcp-playground

# Install dependencies
pnpm install

Set Up Environment

Create a .env.local file in the root directory with the following variables:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/mcp-playground"

# Better Auth
BETTER_AUTH_SECRET="your_secret_key"  # Generate with: openssl rand -hex 32
BETTER_AUTH_URL="http://localhost:3000"

# GitHub OAuth (Required for GitHub login)
GITHUB_CLIENT_ID="your_github_client_id"
GITHUB_CLIENT_SECRET="your_github_client_secret"

# Resend (Required for Magic Link authentication)
RESEND_API_KEY="your_resend_api_key"

# Application-level encryption
ENCRYPTION_KEY="paste_64_char_hex_key"  # Generate with: openssl rand -hex 32

Start Database
```
pnpm docker:db:up
```
Initialize Database
```
pnpm db:push
```
Start the App
```
pnpm dev
```
Open in Browser

Visit http://localhost:3000

Environment Setup

1. Better Auth Setup

Generate a secure secret key for Better Auth:

openssl rand -hex 32

Add to .env.local:

BETTER_AUTH_SECRET="your_generated_secret"
BETTER_AUTH_URL="http://localhost:3000"  # Change to your production URL in production

2. GitHub OAuth Setup (Required for GitHub Login)

Go to GitHub Developer Settings
Click "New OAuth App"
Fill in the application details:
- Application name: MCP Playground (or your preferred name)
- Homepage URL: http://localhost:3000 (development) or your production URL
- Authorization callback URL:
  - Development: http://localhost:3000/api/auth/callback/github
  - Production: https://your-production-url/api/auth/callback/github
Click "Register application"
Copy the Client ID and generate a Client Secret

Add to .env.local:

GITHUB_CLIENT_ID="your_client_id"
GITHUB_CLIENT_SECRET="your_client_secret"

[!WARNING] The authorization callback URL must match exactly what you configure in .env.local, including the protocol (http/https), domain, and path.

3. Resend Setup (Required for Magic Link Authentication)

Go to Resend
Create an account or sign in
Navigate to API Keys in your dashboard
Create a new API key
Add to .env.local:
```
RESEND_API_KEY="re_..."
```

[!NOTE] Magic Link authentication requires a verified domain in Resend for production use. In development, you can use Resend's test mode.

Database Setup

MCP Playground uses PostgreSQL for storing server connections, user data, and request logs.

Start the Database

Run this command to start a local PostgreSQL instance via Docker:

pnpm docker:db:up

This creates a database with:

Container: mcp-playground-db
Database: mcp-playground
Username: postgres
Password: postgres
Port: 5432

Database Commands

Set up database tables:
```
pnpm db:push
```
Create migration files (after schema changes):
```
pnpm db:generate
```
Apply migrations:
```
pnpm db:migrate
```
View database content (Drizzle Studio):
```
pnpm db:studio
```
Stop database:
```
pnpm docker:db:stop
```
Remove database and volumes:
```
pnpm docker:db:clean
```

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | DATABASE_URL | PostgreSQL connection string | Yes | | BETTER_AUTH_SECRET | Secret key for Better Auth encryption | Yes | | BETTER_AUTH_URL | Base URL for authentication callbacks | Yes | | GITHUB_CLIENT_ID | GitHub OAuth application client ID | For GitHub login | | GITHUB_CLIENT_SECRET | GitHub OAuth application client secret | For GitHub login | | RESEND_API_KEY | Resend API key for sending magic link emails | For Magic Link auth | | ENCRYPTION_KEY | 64-character hex key for encrypting OAuth credentials | Yes |

Encryption Setup

Generate a new key locally with openssl rand -hex 32 and add it to .env.local as well as Supabase/Vercel secrets.

Common Commands

Development

pnpm dev:all - Start PostgreSQL container and Next.js dev server
pnpm dev - Start Next.js dev server only (requires DB running)
pnpm build - Build production bundle
pnpm start - Run production server

Code Quality

pnpm lint - Run Ultracite linter (check mode)
pnpm lint:fix - Run Ultracite linter (fix mode)
pnpm format - Format code with Biome
pnpm typecheck - Run TypeScript type checking

Database Management

pnpm docker:db:up - Start PostgreSQL container
pnpm docker:db:stop - Stop PostgreSQL container
pnpm docker:db:down - Stop and remove PostgreSQL container
pnpm docker:db:clean - Stop, remove container and delete volumes
pnpm db:generate - Generate Drizzle migrations from schema
pnpm db:migrate - Run Drizzle migrations
pnpm db:push - Push schema changes directly to database
pnpm db:studio - Open Drizzle Studio GUI

Project Structure

src/
├── app/                          # Next.js App Router
│   ├── api/auth/[...all]/       # Better Auth catch-all route
│   ├── server/[serverId]/       # Server detail page with prefetching
│   ├── oauth/callback/          # OAuth callback handler
│   └── page.tsx                 # Home page
├── components/
│   ├── playground/              # Main playground interface
│   ├── request-logs/            # Request logging UI
│   └── ui/                      # Reusable UI components
├── server/
│   ├── api/routers/             # tRPC API routes
│   ├── services/                # Business logic
│   └── storage/                 # Database access layer
├── lib/
│   ├── trpc/                    # tRPC configuration
│   ├── auth.ts                  # Better Auth config
│   └── mcp/                     # MCP client logic
├── db/
│   ├── schema/                  # Database schemas
│   └── index.ts                 # Drizzle client
└── env.ts                       # Type-safe environment variables

How It Works

Connect to MCP Server: Add an MCP server by providing its HTTP endpoint and authentication details
OAuth Flow: If the server requires OAuth, MCP Playground handles the complete flow securely
Explore Capabilities: Browse available tools, resources, and prompts exposed by the server
Interactive Testing: Execute tools with custom parameters, fetch resources, and test prompts
Request Logging: View detailed JSON-RPC request/response logs for debugging
Multi-Server Management: Connect and switch between multiple MCP servers

License

MIT License - see LICENSE file for details

MCP Servers