DEV Community

Jaypee
Jaypee

Posted on

How to Test MCP Servers: The Complete Guide

#mcp #ai #testing #devtools

The Model Context Protocol (MCP) has become the standard way to give AI assistants like Claude, Cursor, and VS Code Copilot access to external tools. There are now 1,000+ community MCP servers — but a huge number fail on first install. The #1 issue on the official MCP servers repo is literally "server fails to connect."

This guide covers every way to test an MCP server, from quick manual checks to full automated validation.

Why MCP servers fail

Most failures come down to four things:

  • Transport problems — the client can't spawn the process, or stdio gets polluted by log output (a classic: console.log in a Node server corrupts the JSON-RPC stream).
  • Handshake failures — the server doesn't respond to initialize with a valid protocol version.
  • Schema errors — tool input schemas are malformed, so clients reject them.
  • Runtime crashes — the server starts, then dies on the first real tool call.

1. Manual testing with stdio

The quickest sanity check is to spawn the server and send the MCP initialize message by hand:

echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npx -y @modelcontextprotocol/server-filesystem /tmp
Enter fullscreen mode Exit fullscreen mode

If you get a JSON response with "result" and a protocolVersion, the server is alive. If you get nothing, a stack trace, or garbage before the JSON, you've found a transport bug.

2. Testing the JSON-RPC handshake

A proper MCP session follows a strict sequence:

  1. Client sends initialize → server replies with capabilities
  2. Client sends notifications/initialized
  3. Client sends tools/list → server replies with tool definitions
  4. Client sends tools/call → server executes and returns content

Many servers break at step 3 or 4. Testing each step individually tells you exactly where the problem is.

3. Validating tool schemas

Tool schemas must be valid JSON Schema with type: "object" at the root. Common bugs: missing required arrays, wrong types, and empty descriptions. Clients like Claude Desktop silently drop tools with invalid schemas — which is why a server can "connect" but show zero tools.

4. Browser-based testing (the fast way)

This is exactly the problem MCP Workbench was built to solve. Instead of hand-crafting JSON-RPC messages in a terminal, you paste a server command into a browser and get:

  • Instant connection with the full initialize handshake handled for you
  • All discovered tools with their schemas rendered visually
  • One-click tool calls with parameter inputs
  • A raw JSON-RPC console showing every message in both directions

It's free for public servers — try it with any npx MCP server.

5. Automated verification

For CI/CD, you want automated checks: startup time, tool discovery count, schema validity, and a smoke-test tool call. MCP Workbench's verification suite runs all of these and produces a pass/fail report with runtime evidence.

Built with Next.js + a Python aiohttp WebSocket proxy. Questions welcome!

Top comments (0)