mcp-bench

An interactive tool for exploring and testing MCP (Model Context Protocol) servers over HTTP.

Connect to any MCP server, browse its tools, prompts, and resources, and execute them - all from a clean web UI.

Features

• Browse and execute tools, prompts, and resources exposed by an MCP server
• OAuth support with Dynamic Client Registration (DCR) and PKCE
• Automatic token refresh when access tokens expire
• Falls back to manual Bearer token input when OAuth isn't available
• Handles both JSON and SSE (Server-Sent Events) MCP transport responses
• Dark-themed, minimal UI with no external styling dependencies

Installation

npm install -g mcp-bench

Or run directly without installing:

npx mcp-bench --url=http://your-mcp-server.example.com/mcp

Usage

mcp-bench --url=<MCP server URL>

This starts a local web server on a random available port, opens your browser, and presents a UI to interact with the MCP server.

Options

| Flag | Description | |------|-------------| | --url=<url> | (required) The HTTP URL of the MCP server to connect to |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | Pin the local web server to a specific port | auto (random available) |

Examples

# Connect to a local MCP server
mcp-bench --url=http://localhost:8080/mcp

# Connect to a remote MCP server on a custom port
PORT=4000 mcp-bench --url=https://mcp.example.com/api

# Run via npx without global install
npx mcp-bench --url=http://localhost:8080/mcp

Authentication

OAuth (automatic)

When the MCP server returns 401 Unauthorized, mcp-bench will:

1. Check /.well-known/oauth-protected-resource on the MCP server
2. Discover the authorization server via /.well-known/oauth-authorization-server
3. If the server supports Dynamic Client Registration, register automatically and redirect you to login
4. After authorization, the token is stored in-session and refreshed automatically on expiry

Manual Token

If the MCP server doesn't support OAuth discovery or DCR, you'll be prompted to paste a Bearer token manually.

Development

# Install dependencies
npm install

# Run the Vite dev server (with HMR) for the frontend
npm run dev:client

# In another terminal, start the backend pointed at your MCP server
node bin/cli.js --url=http://localhost:8080/mcp

# Build the frontend for production
npm run build:client

The Vite dev server proxies /api requests to http://localhost:3456, so both can run simultaneously during development.

How It Works

┌─────────────┐       ┌──────────────┐       ┌────────────────┐
│   Browser   │──────▶│  mcp-bench   │──────▶│   MCP Server   │
│  (React UI) │◀──────│  (Express)   │◀──────│  (target URL)  │
└─────────────┘       └──────────────┘       └────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │  OAuth Server │  (if auth required)
                    └───────────────┘

• The Express server acts as a proxy between the browser and the MCP server
• It manages sessions, OAuth tokens, and MCP session IDs
• The React frontend is built with Vite and served as static assets by Express

License

ISC