Mcp Playground

MCP Playground

A web-based UI for connecting to, managing, and interacting with Model Context Protocol (MCP) servers. It lets you add servers (via stdio or HTTP), browse their tools, resources, and prompts, and call tools — all from a browser interface.

> ⭐ If you find this project useful, please consider giving it a star — it helps others discover it!

Why?

Debugging MCP servers typically requires connecting them to an LLM, which costs tokens and money. MCP Playground lets you call tools, read resources, and inspect prompts directly — no LLM needed.

Features

• 🔌 Connect to MCP servers over stdio (subprocess) or HTTP (SSE / Streamable HTTP)
• 🛠️ Browse and call tools exposed by any connected server
• 📄 Read resources and retrieve prompts
• 💾 Persist server configurations in mcp-servers.json
• 🗑️ Add, edit, and delete servers from the UI
• 🗂️ Stdio server processes run in isolated per-server directories under .mcp-data/ (gitignored)
• ⚡ Hot-reload dev environment (server + client run concurrently)

Tech Stack

| Layer | Technology | |---|---| | Backend | Hono on Node.js (TypeScript) | | Frontend | React + Vite (TypeScript) | | MCP SDK | @modelcontextprotocol/sdk | | Runtime | tsx (no compile step in dev) |

Architecture

flowchart TD
    subgraph Browser["Browser (localhost:5173)"]
        UI["React UI"]
    end

    subgraph Server["Node.js Server (localhost:8000)"]
        Hono["Hono HTTP API\n/api/servers/*"]
        McpManager["McpManager\n(singleton)"]
        Config["mcp-servers.json\n(persistence)"]
        Hono --> McpManager
        McpManager --> Config
    end

    subgraph MCPServers["MCP Servers"]
        Stdio["Stdio Server\n(subprocess)"]
        HTTP["HTTP Server\n(SSE / Streamable-HTTP)"]
    end

    UI -- "REST /api" --> Hono
    McpManager -- "spawn + stdin/stdout" --> Stdio
    McpManager -- "HTTP transport" --> HTTP

Getting Started

Prerequisites

• Node.js 20+
• npm

Install

npm install
npm --prefix client install

Run (dev)

npm run dev

• API server → http://localhost:8000
• UI → http://localhost:5173

Run (production)

npm run build
npm start

The Hono server will serve the built client from http://localhost:8000.

Configuration

Server connections are persisted in mcp-servers.json at the project root. You can also manage them live through the UI or REST API.

Stdio server example:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {}
    }
  }
}

HTTP server example:

{
  "mcpServers": {
    "my-http-server": {
      "url": "http://localhost:3000/mcp",
      "transport": "sse"
    }
  }
}

> Note: mcp-servers.json is gitignored so your local server configs are never committed. Copy mcp-servers.example.json as a starting point: > ``bash > cp mcp-servers.example.json mcp-servers.json > ``

> Note: Each stdio server process runs with its working directory set to .mcp-data//. This folder is created automatically and gitignored, so any files an MCP server creates (e.g. browser profiles, caches) stay out of the repo.

API Reference

| Method | Path | Description | |---|---|---| | GET | /api/servers | List all servers | | POST | /api/servers | Add a server | | PUT | /api/servers/:id | Update a server | | DELETE | /api/servers/:id | Remove a server | | POST | /api/servers/:id/connect | Connect to a server | | POST | /api/servers/:id/disconnect | Disconnect | | GET | /api/servers/:id/tools | List tools | | POST | /api/servers/:id/tools/:tool/call | Call a tool | | GET | /api/servers/:id/resources | List resources | | POST | /api/servers/:id/resources/read | Read a resource | | GET | /api/servers/:id/prompts | List prompts | | POST | /api/servers/:id/prompts/:prompt/get | Get a prompt |

Contributing

Issues and PRs are welcome! Feel free to open an issue to report a bug or suggest a feature, or submit a pull request with your changes.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JoseMiguez98
• Source: JoseMiguez98/mcp-playground
• License: MIT

Install and usage instructions live in the source repository linked above.