mcp-harness

mcp-harness provides an in-memory test harness for MCP servers written in TypeScript. It lets you import your McpServer instance and connect a harness directly to it, avoiding subprocesses, ports, and I/O. This makes it ideal for fast, reliable tests and CI integration, acting similarly to supertest but tailored for the MCP (Model Context Protocol) ecosystem. You can register tools, resources, prompts, and then invoke tools or read resources through a unified harness API, inspect results, and assert on text content or errors without dealing with serializing or socket communication.

In practice, you typically create a McpServer in your test code, attach tools that return structured MCP results, and then instantiate a harness via createHarness. In in-memory mode, you pass your McpServer instance directly to createHarness and interact entirely in-process. In subprocess mode, you can test a real MCP server executable by supplying a SubprocessConfig with a command, arguments, and environment, mirroring how a client would connect in production. The harness exposes methods like listTools, callTool, listResources, readResource, listPrompts, and getServerCapabilities, enabling end-to-end testing of your server’s behavior and responses.

Whether you’re validating tool outputs, resource reads, or prompt resolution, mcp-harness provides assertion helpers to examine text within tool results, verify errors, and check for the existence of tools, resources, and prompts. It’s designed to be framework-agnostic, so you can use Vitest, Jest, node:assert, or your preferred test runner to write expressive MCP tests.

Prerequisites:

• Node.js (>= 14.x or newer) and npm or pnpm
• A TypeScript-based MCP server project, or a compiled MCP server that exports an McpServer instance

Step-by-step:

1. Create a project directory (if starting fresh) and initialize npm:

   mkdir my-mcp-project cd my-mcp-project npm init -y

2. Install the harness and its peer dependency:

   npm install --save-dev mcp-harness npm install --save @modelcontextprotocol/sdk

3. If you’re building a TypeScript MCP server, ensure your server exports an McpServer instance that can be consumed by the harness. See the library’s integration guide for how to expose the server for testing.

4. (Optional) If you plan to run a real MCP server as a subprocess, ensure you have a runnable entrypoint (e.g., dist/server.js) and that your environment variables are configured as needed for tests.

5. Add a test script or test files that use createHarness to connect to your in-memory server or to a subprocess configuration as demonstrated in the README.

Tips and notes:

• In-memory mode is the fastest and most deterministic way to test MCP servers; use it for unit and integration tests where possible.
• Subprocess mode is useful to validate your server’s runtime behavior, startup, and CLI/transport interactions against a real process.
• If your server requires API keys or environment-specific settings, supply them via the env object in SubprocessConfig or set them in your test environment for in-memory mode.
• When testing, you can rely on helper assertions like hasText, getFirstText, resourceExists, and promptExists to quickly verify common MCP results.
• The npm package name is mcp-harness and it expects @modelcontextprotocol/sdk to be installed as a peer dependency for full compatibility.