MCP testing SDK

Test your MCP server in code.

The @mcpjam/sdk connects to any MCP server, runs its tools on their own or against a real LLM, scores agent-in-the-loop evals, and checks OAuth conformance. It's plain TypeScript, so it runs in Jest or any test runner.

Read the SDK docs Open the web app

server.test.ts — mcp-serverVitest

server.test.tsmcp.json

1import { test, expect } from "vitest";
2import { MCPClientManager } from "@mcpjam/sdk";
3 
4const mcp = new MCPClientManager({
5  pokemon: { command: "python", args: ["pokemon_mcp.py"] },
6});
7 
8test("lists the expected tools", async () => {
9  const { tools } = (await mcp.listTools("pokemon")).result;
10  expect(tools.some((t) => t.name === "get_pokemon")).toBe(true);
11});
12 
13test("executes get_pokemon", async () => {
14  const res = await mcp.executeTool("pokemon", "get_pokemon", {
15    name: "pikachu",
16  });
17  expect(res.content[0].text).toContain("Pikachu");
18});

npx vitest runRUNNING

lists the expected tools

executes get_pokemon

Tests 0 passed (2)Duration 412ms

From client setup to OAuth conformance

Set up MCP clients

MCPClientManager connects to any server using the same config shape as an mcp.json file, so your test setup matches production.

Unit and end-to-end tests

Call a tool directly for a deterministic unit test, or put a real LLM in front of your server and assert on what it calls with toolsCalled() for an end-to-end run.

Agent-in-the-loop evals

Model output changes from run to run, so run a prompt across many iterations with EvalTest and read the pass rate from accuracy().

OAuth conformance

Validate auth across every protocol version and registration method in one suite. It runs the whole OAuth debugger flow as a test and exports JUnit XML for CI.

Test what a real model calls

Connect a server, hand its tools to a model, and assert on the tools it invokes.

server.test.ts

import { MCPClientManager, HostRunner } from "@mcpjam/sdk";

test("the model calls the add tool", async () => {
  const manager = new MCPClientManager({
    server: { command: "node", args: ["dist/server.js"] },
  });

  const runner = new HostRunner({
    tools: await manager.getToolsForAiSdk(),
    model: "anthropic/claude-sonnet-4-20250514",
    apiKey: process.env.ANTHROPIC_API_KEY,
  });

  const result = await runner.run("Add 2 and 3");
  expect(result.toolsCalled()).toContain("add");
});

Frequently asked questions

A TypeScript SDK for testing MCP servers in code. It connects to any server, runs unit and end-to-end tests, scores agent-in-the-loop evals, and checks OAuth and protocol conformance. Everything runs in Jest, Vitest, or any runner.

Three, plus conformance. Unit tests call a tool directly and assert on the result, with no model involved. End-to-end tests put a real LLM in front of your server and check that it uses the tool correctly. Evals run that same path across many iterations and score it, since model output varies. Conformance suites check your server against the MCP and OAuth specs.

Yes. The OAuth conformance suite validates your auth across every protocol version and registration method in one run. It gives the same coverage as stepping through the OAuth debugger by hand, and exports JUnit XML for CI.

Yes. It's plain TypeScript that runs in Jest, Vitest, or any runner, so the same tests run locally and in GitHub Actions. See CI/CD actions.

Put MCP testing in your pipeline.

Run unit tests, end-to-end runs, evals, and conformance in code, then gate every PR on the results.

Read the SDK docs Talk to us

Open source · npm install @mcpjam/sdk

Keep exploring

CLI

Run the same checks from the command line.

CI/CD actions

Wire evals and tests into every PR.

Docs

SDK reference and guides.