Vitest-native testing for MCP servers
Matchers, snapshots, interaction doubles, and real external servers, on both MCP SDK majors.
$npm i -D mcp-vitest
latest v0.5.1 on npmTest output
One suite, both protocol eras
The same tests against both SDK majors. Each pane reports the revision its lane negotiated rather than assuming one.
test/*.test.ts - 160 tests, every suite that runs on both lanes
SDK v12025-11-25
- completes a prompt argument by prefix18ms
- a non-matching prefix completes to nothing1ms
- completes a resource-template variable1ms
- toolManifest is stable and sorted20ms
- capabilitiesManifest lists names only4ms
- readResource returns contents1ms
- listResources and listPrompts include fixtures2ms
- getPrompt renders arguments1ms
- onProgress receives updates246ms
- signal cancels a slow call54ms
- timeoutMs rejects a slow call104ms
11 passed (11)
SDK v22026-07-28
- completes a prompt argument by prefix52ms
- a non-matching prefix completes to nothing9ms
- completes a resource-template variable3ms
- toolManifest is stable and sorted59ms
- capabilitiesManifest lists names only5ms
- readResource returns contents3ms
- listResources and listPrompts include fixtures4ms
- getPrompt renders arguments2ms
- onProgress receives updates310ms
- signal cancels a slow call55ms
- timeoutMs rejects a slow call106ms
11 passed (11)
The matrix
Every SDK major, every protocol revision
| Lane | 2025-11-25 | 2026-07-28 |
|---|---|---|
| v1 | the only revision it negotiates | throws - the v1 SDK cannot serve it |
| v2 | legacy mode, no doubles available | default, full support |
| stdio | the only revision it negotiates | throws - stdio is driven by v1 |
| url | legacy mode, no doubles available | pinned, otherwise auto-negotiated |
Coverage
What mcp-vitest covers
- Both SDK majors
- v1 and v2 servers, detected automatically. No adapter to write.
- Lifecycle coverage
- Run the same tests against the 2025 and 2026-07-28 protocol revisions.
- Interaction doubles
- Answer a server's sampling, elicitation, and roots requests from your test.
- Notifications and progress
- Collect what a server pushes, or await one by method. Progress and cancellation per call.
- Typed matchers
- Seven of them, with TypeScript augmentation and did-you-mean suggestions.
- External servers
- Spawn one over stdio or point at a running URL. Everything else works unchanged.
- OAuth testing
- Send bearer credentials to a URL server, or drive the other side with a fake authorization server.
- Regression safety
- Snapshot manifests normalized so key order and absent optionals never churn them.
Requirements
What your project needs
| Requirement | Value |
|---|---|
| Node.js | >=20 |
| vitest | ^3.2.0 || ^4.0.0 |
| Module format | ESM only |
| @modelcontextprotocol/sdk | ^1.17.0, optional |
| @modelcontextprotocol/client | ^2.0.0, optional |
| @modelcontextprotocol/server | ^2.0.0, optional |
All three SDK peers are optional - install whichever major your server uses, and mcpTest() detects it at runtime. Five subpath exports, all typed:
- .
- ./matchers
- ./setup
- ./snapshot
- ./auth
Alternatives
Compared to the alternatives
marks the tool ahead on that row, whichever tool it is
mcp-vitest
- SDK majors
- Leads: v1 and v2, auto-detected
- Protocol revisions
- Leads: 2025-11-25 and 2026-07-28
- Interaction doubles
- Leads: sampling, elicitation, roots
- Snapshots
- Leads: Normalized manifests
- Schema validation
- Leads: toMatchOutputSchema
- OAuth testing
- Fake authorization server, bearer credentials
- External servers
- stdio or URL
- Notifications
- Leads: Collected, or awaited by method, with progress/cancellation
- SDK majors
- v1 only, per its own peer range >=1.10.0 <2
- Protocol revisions
- Whatever v1 negotiates
- Interaction doubles
- No
- Snapshots
- No
- Schema validation
- No
- OAuth testing
- No
- External servers
- No - in-memory transport only
- Notifications
- No
- SDK majors
- Interactive tool, not a test harness
- Protocol revisions
- -
- Interaction doubles
- -
- Snapshots
- -
- Schema validation
- -
- OAuth testing
- Leads: Interactive OAuth flows, own auth core
- External servers
- Core use case - stdio and HTTP, either era
- Notifications
- Viewed live in the UI
Hand-rolled
- SDK majors
- Whatever you write twice
- Protocol revisions
- Whatever you pin
- Interaction doubles
- Whatever you wire
- Snapshots
- Yours to normalize
- Schema validation
- Yours to write
- OAuth testing
- Whatever you implement
- External servers
- However you spawn it
- Notifications
- Whatever you subscribe 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. MCP Inspector solves a different problem: it is for looking at a server by hand, not for assertions in a suite.
The project
By the numbers
- 1,027
- downloads a month
- 11.58 kB
- minified + gzipped
- 75 kB
- unpacked size
- 2
- GitHub stars
Contributor
Same suite. Both SDK majors. Both protocol eras.
$npm i -D mcp-vitest