mcp-vitest

Test your MCP server the way you test everything else.

In-process · both SDK majors · both protocol revisions · seven typed matchers · one runtime dependency
_{A fresh server plus a full initialize handshake, per test, costs 0.24ms on SDK v1 and 0.47ms on v2 - means across 8,270 and 4,284 samples at ±2.3% and ±3.6%, reproducible with npm run bench. There is no subprocess and no socket to pay for. Also checkable: 160 tests across the two SDK lanes, which connect over different transports and so are covered separately rather than assumed equivalent; the v2 lane pins the 2026-07-28 revision, which is what makes the two lanes cover different protocol eras instead of the same one twice; and every build is verified with publint and @arethetypeswrong/cli. See the runs.}

Documentation · Getting started · API reference · Lifecycles

_{AI agents / LLMs: the documentation is machine-readable at llms.txt, or as one blob at llms-full.txt.}

Contents

• mcp-vitest
  • Contents
  • Before and after
  • Overview
  • Features
  • Getting started
    • Prerequisites
    • Install
    • Quickstart
  • Works with both SDK majors
  • Testing OAuth-protected servers
  • API
  • Is this for you
  • Compared to
  • FAQ
  • Contributing
  • Contributors
  • License
  • Support the project
  • Connect

Before and after

Driving an MCP server from a test without a harness means wiring the SDK yourself. This is a trimmed version of what src/connect/v1.ts does for you - a linked transport pair, a client with the right capabilities advertised before initialize, and a request handler per interaction type:

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

const client = new Client(
  { name: "my-test", version: "1.0.0" },
  { capabilities: { sampling: {}, elicitation: {}, roots: {} } },
);

client.setRequestHandler(CreateMessageRequestSchema, async (req) =>
  mySampling(req.params),
);
client.setRequestHandler(ElicitRequestSchema, async (req) =>
  myElicitation(req.params),
);
client.setRequestHandler(ListRootsRequestSchema, async () => ({
  roots: myRoots,
}));

await Promise.all([
  server.connect(serverTransport),
  client.connect(clientTransport),
]);

const { tools } = await client.listTools();
if (!tools.some((t) => t.name === "search")) throw new Error("no search tool");

And that is only the v1 path. A v2 server does not use InMemoryTransport at all - it connects over the SDK's in-process handler.fetch route - so supporting both means writing it twice and keeping them in step.

With the harness:

const test = createMcpTest(() => createServer());

test("search tool works", async ({ mcp }) => {
  await expect(mcp).toHaveTool("search");
});

mcpTest() detects which SDK your server came from and routes to the matching transport. Capabilities are advertised before initialize because a server decides what to request during it, which is a detail that is easy to get wrong by hand and impossible to notice until a double never fires.

Overview

Testing an MCP server usually means spawning a subprocess, picking a port, or hand-rolling JSON-RPC frames. By default mcp-vitest does none of that: your server runs in-process, driven by a real SDK Client over the SDK's own in-process transport, and you get a small harness plus typed matchers on top. When a server cannot be imported, the same harness drives it over stdio or a URL instead. The protocol is never reimplemented, so what your tests exercise is what a real client would.

   your test ──▶ mcp.callTool() ──▶ real SDK Client ──┬─▶ v1: InMemoryTransport pair
   expect(mcp) ─▶ seven matchers                      ├─▶ v2: handler.fetch route
                                                      └─▶ external: stdio or URL

Features

• In-process by default - no ports, no spawn, no teardown races. Both SDK majors, detected automatically.
• Typed matchers - seven of them, with TypeScript augmentation and did-you-mean suggestions on typos.
• A small harness - tools, resources, and prompts with pagination followed for you, plus the raw SDK client as an escape hatch.
• Interaction doubles - answer a server's sampling, elicitation, and roots requests from your test.
• External servers - spawn one over stdio or point at a running URL; everything above works unchanged.
• OAuth test doubles - send a bearer token or headers with auth, and drive the other side of the handshake with a fake authorization server backed by a real RS256 keypair.
• Lifecycle coverage - run the same tests against the 2025 and 2026-07-28 protocol revisions.
• Regression safety - snapshot manifests normalized so key order and absent optionals never churn them.
• Real call ergonomics - progress callbacks, AbortSignal cancellation, per-call timeouts, and a notification collector with waitFor.
• One runtime dependency - @cfworker/json-schema (MIT, no transitive deps). Your MCP SDK is an optional peer, so you install only the major you use.

Getting started

Prerequisites

• Node.js >=20
• vitest >=3.2 in your project
• An MCP server built on either SDK major - @modelcontextprotocol/sdk >=1.10, or @modelcontextprotocol/server + /client ^2.0. Both are optional peers, so you install only the one you use.
• ESM only, with no CJS build

Install

npm i -D mcp-vitest vitest

Plus the SDK your server uses:

# SDK v1
npm i -D @modelcontextprotocol/sdk

# SDK v2
npm i -D @modelcontextprotocol/server @modelcontextprotocol/client

Quickstart

Register the matchers in your vitest config:

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: { setupFiles: ["mcp-vitest/setup"] },
});

Then test your server:

import { expect } from "vitest";
import { createMcpTest } from "mcp-vitest";
import { createServer } from "./src/server.js";

const test = createMcpTest(() => createServer());

test("search tool works", async ({ mcp }) => {
  await expect(mcp).toHaveTool("search");
  const result = await mcp.callTool("search", { query: "foo" });
  expect(result).toHaveTextContent(/results/);
});

(Set globals: true in your vitest config if you would rather skip the expect import.)

Works with both SDK majors

• v1 (@modelcontextprotocol/sdk) connects over the SDK's InMemoryTransport linked pair.
• v2 (@modelcontextprotocol/server) connects over the SDK's in-process handler.fetch route.

You do not pick. mcpTest() detects which SDK your server came from and routes to the matching transport; mcp.kind reports what it found. The same tests, matchers, and fixture work either way - including against external servers, which report 'external'. Which protocol revision each lane speaks is covered under lifecycles.

Testing OAuth-protected servers

Pass auth: { token } or auth: { headers } to send credentials on every request, and reach for mcp-vitest/auth to test the other side of the handshake: a fake authorization server with a real RS256 keypair, plus assertions for the 401 challenge and PRM discovery a protected server has to get right. Details at auth test doubles.

Pass fakeAuthServer({ audience }) when your server should refuse a token minted for a different resource - MCP's confused-deputy defence. Without it the verifier accepts any audience, reporting a URL-shaped one as AuthInfo.resource for a server that reads it, because requireBearerAuth checks only scopes and expiry. auth throws on a stdio or in-process server, which cannot send a credential at all.

API

The full reference lives at mcp-vitest.nixrajput.com/en/docs/api/mcp-test - mcpTest, the harness, all seven matchers, interaction doubles, notification collectors, snapshots, external servers, and the lifecycle matrix.

Migrating from an earlier version? See the migration notes.

Is this for you

Good fit if you…

• maintain an MCP server and want tests that run in your existing vitest suite
• need to assert on tools, resources, prompts and results without hand-rolling JSON-RPC
• have to answer a server's sampling, elicitation or roots requests from a test
• support both SDK majors, or are migrating between them
• care which protocol revision your server actually negotiates

Skip it if you…

• want an interactive debugger rather than automated tests. MCP Inspector is the right tool for poking at a server by hand.
• are not on vitest. The matchers and fixture are vitest-native; nothing here ports to jest without rewriting.
• only need to check that a process starts. A shell script is cheaper.
• are on SDK v1 below 1.10, or need a CJS build. This is ESM only.

Compared to

vitest-mcp arrived in August 2026 and covers the same idea for the v1 SDK; if that is all you need, it is smaller. The differences above are the reasons this exists: two SDK majors over two different transports, two protocol eras, and the interaction doubles that let a test answer what a server asks it.

FAQ

Does it spawn my server as a subprocess? Not by default. When a server cannot be imported, the same harness drives it over stdio or a URL instead, and everything else works unchanged.

Is the protocol reimplemented? No - both lanes use the SDK's own client and transports. That is also why the lanes are tested separately rather than assumed equivalent: they genuinely connect differently.

Which protocol revision am I testing? Whichever your lane negotiates, and it is reported rather than assumed. SDK v1 tops out at 2025-11-25; the v2 lane pins 2026-07-28. Asking a v1 server for the 2026 lifecycle fails with an explanation instead of silently testing the older era. See lifecycles.

Is the fake authorization server a mock? No - it is a real HTTP server with its own RS256 keypair, serving real JWKS and token endpoints, so your requireBearerAuth wiring runs unchanged rather than being stubbed out. Two instances never trust each other's tokens, because each mints its own keypair.

Why is there a runtime dependency at all? toMatchOutputSchema needs a validator, and v1 emits draft-07 while v2 emits 2020-12. @cfworker/json-schema is MIT with no transitive dependencies, and v1 users pay nothing extra because the MCP SDK already depends on it. Approximating validation in a testing tool would be worse than the dependency.

Can I use the raw SDK client? Yes. The harness exposes it as an escape hatch, so anything not covered by a matcher is still reachable.

Contributing

Contributions are welcome. Fork, branch, and open a PR - see CONTRIBUTING.md for the checks a PR has to pass. Bugs and ideas go to Issues; questions to Discussions; vulnerabilities follow SECURITY.md.

Contributors

Thanks to everyone who has contributed to mcp-vitest.

License

Licensed under the MIT license - see LICENSE.

Support the project

mcp-vitest is MIT licensed and free to use, always. If it earns a place in your test suite, sponsorship is welcome.

Connect

Nikhil Rajput