Unit Testing and Mocking MCP Servers Guide

+-----------------------------------------------------------------------+
|                    VITEST / JEST TEST RUNNER                          |
|         it("should validate schemas and return formatted results")    |
+-----------------------------------+-+---------------------------------+
                                    |
                                    | Direct In-Memory JavaScript Calls
                                    v
+-----------------------------------------------------------------------+
|                       MOCK MCP CLIENT INSTANCE                        |
|                     (Client from @modelcontextprotocol/sdk)           |
+-----------------------------------+-+---------------------------------+
                                    |
                                    | InMemoryTransport (Pair)
                                    v
+-----------------------------------------------------------------------+
|                       TARGET MCP SERVER UNDER TEST                    |
|                     (Server from @modelcontextprotocol/sdk)           |
|                                                                       |
|  1. Request Schema Validation (Zod parser asserts arguments)          |
|  2. Tool Handler Execution (Calls business logic)                     |
|  3. JSON-RPC Frame Serialization (Formats result or error block)      |
+-----------------------------------+-+---------------------------------+
                                    |
                                    | Intercepted Network Calls
                                    v
+-----------------------------------------------------------------------+
|                     MOCK SERVICE WORKER (MSW)                         |
|     Intercepts external HTTP APIs (GitHub, Stripe, PostgreSQL)        |
+-----------------------------------------------------------------------+

npm install --save-dev vitest @modelcontextprotocol/sdk zod msw

{
  "mcpServers": {
    "calculator-service": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

{
  "mcpServers": {
    "calculator-service": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

# ~/.codex/config.toml
[mcp_servers.calculator_service]
command = "node"
args = ["dist/index.js"]

[mcp_servers.calculator_service.env]
NODE_ENV = "production"
LOG_LEVEL = "warn"

// src/calculator-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  ListToolsRequestSchema,
  CallToolRequestSchema,
  ErrorCode,
  McpError
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const CompoundInterestSchema = z.object({
  principal: z.number().positive(),
  rate: z.number().min(0).max(1),
  years: z.number().int().positive()
});

export function createCalculatorServer(): Server {
  const server = new Server(
    { name: "calculator-mcp", version: "1.0.0" },
    { capabilities: { tools: {} } }
  );

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: "calculate_compound_interest",
        description: "Calculate compound interest over time.",
        inputSchema: {
          type: "object",
          properties: {
            principal: { type: "number", description: "Initial investment" },
            rate: { type: "number", description: "Annual interest rate as decimal (e.g. 0.05)" },
            years: { type: "number", description: "Duration in years" }
          },
          required: ["principal", "rate", "years"]
        }
      }
    ]
  }));

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name !== "calculate_compound_interest") {
      throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${request.params.name}`);
    }

    const parseResult = CompoundInterestSchema.safeParse(request.params.arguments);
    if (!parseResult.success) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Validation failed: ${parseResult.error.message}`
      );
    }

    const { principal, rate, years } = parseResult.data;
    const finalAmount = principal * Math.pow(1 + rate, years);

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ principal, rate, years, total: Number(finalAmount.toFixed(2)) })
        }
      ]
    };
  });

  return server;
}

// tests/calculator-server.test.ts
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
import { createCalculatorServer } from "../src/calculator-server.js";

describe("Calculator MCP Server Tests", () => {
  let client: Client;
  let serverTransport: InMemoryTransport;
  let clientTransport: InMemoryTransport;

  beforeEach(async () => {
    // 1. Create linked in-memory transport pair
    [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

    // 2. Initialize client and server
    const server = createCalculatorServer();
    client = new Client(
      { name: "test-client", version: "1.0.0" },
      { capabilities: {} }
    );

    // 3. Connect transports simultaneously
    await Promise.all([
      server.connect(serverTransport),
      client.connect(clientTransport)
    ]);
  });

  afterEach(async () => {
    await clientTransport.close();
    await serverTransport.close();
  });

  it("should advertise the calculate_compound_interest tool in tools/list", async () => {
    const response = await client.listTools();
    expect(response.tools).toHaveLength(1);
    expect(response.tools[0].name).toBe("calculate_compound_interest");
    expect(response.tools[0].inputSchema.required).toEqual(["principal", "rate", "years"]);
  });

  it("should successfully compute compound interest for valid parameters", async () => {
    const result = await client.callTool({
      name: "calculate_compound_interest",
      arguments: { principal: 1000, rate: 0.05, years: 10 }
    });

    expect(result.content).toHaveLength(1);
    const parsed = JSON.parse(result.content[0].text);
    expect(parsed.total).toBe(1628.89);
  });

  it("should return InvalidParams error code when required argument is missing", async () => {
    await expect(
      client.callTool({
        name: "calculate_compound_interest",
        arguments: { principal: 1000, rate: 0.05 } // missing years
      })
    ).rejects.toThrowError();
  });

  it("should reject negative principal amounts with schema validation error", async () => {
    try {
      await client.callTool({
        name: "calculate_compound_interest",
        arguments: { principal: -500, rate: 0.05, years: 5 }
      });
      expect.fail("Should have thrown McpError");
    } catch (err: any) {
      expect(err.code).toBe(ErrorCode.InvalidParams);
      expect(err.message).toContain("Number must be greater than 0");
    }
  });

  it("should return MethodNotFound when invoking an unlisted tool", async () => {
    try {
      await client.callTool({
        name: "non_existent_tool",
        arguments: {}
      });
      expect.fail("Should have thrown McpError");
    } catch (err: any) {
      expect(err.code).toBe(ErrorCode.MethodNotFound);
    }
  });
});

// tests/mocks/handlers.ts
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";

export const handlers = [
  http.get("https://api.github.com/repos/:owner/:repo/issues", ({ params }) => {
    const { owner, repo } = params;
    return HttpResponse.json([
      { id: 101, number: 42, title: `Issue for ${owner}/${repo}`, state: "open" }
    ]);
  }),
  http.post("https://api.stripe.com/v1/customers", () => {
    return HttpResponse.json({ id: "cus_mock123", object: "customer" });
  })
];

export const mockHttpServer = setupServer(...handlers);

// tests/setup.ts
import { beforeAll, afterEach, afterAll } from "vitest";
import { mockHttpServer } from "./mocks/handlers.js";

beforeAll(() => mockHttpServer.listen({ onUnhandledRequest: "error" }));
afterEach(() => mockHttpServer.resetHandlers());
afterAll(() => mockHttpServer.close());