Documentation

The definitive technical guide to testing, diagnosing, and deploying Model Context Protocol (MCP) servers locally and in production.

What is MCPHub?

MCPHub is built specifically to bridge the gap between building an MCP server and actually deploying it with confidence. It gives you the tools to introspect requests, check server latencies, and simulate real-world LLM calls via a Playground.

If you are building tools for LLMs, you need a way to test them exactly as an LLM would execute them. Our UI provides a fully typed, real-time interface to list tools, compile prompts, and observe JSON-RPC streams.

The Postman-like Client

The Playground is your primary workspace. Think of it as Postman, but specifically tailored to MCP JSON-RPC endpoints instead of REST.

  • Connecting: You can spin up any local command (e.g., node index.js) or connect to an SSE HTTP endpoint. The Playground will instantly negotiate the protocol version and fetch server capabilities.
  • Tool Execution: Our UI automatically generates forms based on the JSON Schema of your tools. Provide the arguments, hit "Run", and view the raw JSON-RPC response instantly. No more writing manual curl commands.
  • Protocol Inspector: Every single payload going over the wire is captured in the Inspector. You can filter by direction, check latency (P50/P99), and instantly spot syntax errors or malformed tool definitions.

Handling Credentials

Many popular MCP servers (like GitHub, Slack, or Postgres) require API keys, OAuth tokens, or database connection strings. Here is how you securely pass them into the Playground.

GitHub Server (Via mcp-proxy)

Since GitHub runs locally via stdio and MCPHub is a web app, you must wrap it in an SSE server using mcp-proxy. Generate a PAT with repo permissions, then run this in a terminal:

GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxx" npx -y mcp-proxy@latest --shell -- npx -y @modelcontextprotocol/server-github

Slack Server

Obtain a Bot User OAuth Token from your Slack App dashboard. Ensure the app is installed to your workspace.

SLACK_BOT_TOKEN=xoxb-xxx node build/index.js

Postgres Server

Use a standard connection string for the database server.

DATABASE_URL=postgres://user:pass@localhost:5432/db npx @server/postgres

Google Drive Server

Requires a Service Account JSON key or OAuth consent screen setup depending on the implementation.

GOOGLE_APPLICATION_CREDENTIALS=./key.json node index.js

Pro Tip: When using the Playground's Connect Form, you can add environment variables directly in the "Env Vars" section. These are injected safely before spawning the local process.

Adding Custom Servers

Building a custom MCP Server is straightforward using the official SDKs (TypeScript and Python).

Once built, you can test it directly in MCPHub by selecting Command (Stdio) in the connection form and providing the path to your server.

// Example Python Command
Command: python
Arguments: -m my_mcp_server
Environment: API_KEY=xxx

If your server uses HTTP/SSSE, ensure CORS is enabled and point the Playground to the correct /sse endpoint.

Desktop Agent

The Desktop Agent is a small local process that bridges the cloud-deployed MCPHub to MCP servers running on your machine. Without it, the deployed app cannot reach localhost — because localhost on Vercel refers to Vercel's server, not yours.

How it works: The agent runs on your machine and listens on ws://localhost:54319. MCPHub detects it automatically and shows a green ⚡ DESKTOP AGENT DETECTED banner in the connect form. Enable the toggle and all MCP traffic routes through the agent instead of Vercel.

Step 1 — Install the Agent

Install globally from npm (one-time setup, Node.js 18+ required):

npm install -g @naman_411/mcphub-agent

On Windows, run the terminal as Administrator if you get a permissions error.

Step 2 — Start the Agent

mcphub-agent start

# Custom port (optional)
mcphub-agent start --port 8888

You should see: 🚀 MCPHub Agent listening on ws://localhost:54319

Step 3 — Connect a Local Server

  1. Open the Playground — the green ⚡ DESKTOP AGENT DETECTED banner appears automatically when the agent is running.
  2. Enable the toggle in the banner.
  3. Enter your local server URL (e.g. http://localhost:8080/sse) or switch to Command (Stdio) and type the command directly.
  4. Click INITIALIZE. The agent handles the connection on your machine.

SSE / Streamable HTTP

Use for servers you started separately that expose an HTTP endpoint.

http://localhost:8080/sse

Stdio (Command)

The agent spawns the process directly on your machine. Add env vars in the form.

npx -y @modelcontextprotocol/server-github

CLI Tools & Automation

While the UI is perfect for human testing, you need CLI tools for CI/CD pipelines. The official MCP organization provides a powerful inspector CLI.

# Run the official MCP Inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js

This command launches a local process and opens a web interface that allows you to inspect messages and execute tools directly. It's the command-line equivalent of the Playground you see here.

If you are creating automated tests, consider using the @modelcontextprotocol/sdk in your test runner (e.g., Jest or PyTest) to spawn a client instance and assert against your server's responses programmatically.