write-mcp-test

Write MCP server tests

A test checks a server directly: it calls a tool with fixed arguments through MST's mcp fixture and asserts on the response with MST's matchers. Tests are fast and deterministic, so run each once, in CI.

A test has no client and no model, so it can't tell you whether a model would pick the tool. That is an eval: use the write-mcp-eval skill.

Before you start

1. Check that the project has @gleanwork/mcp-server-tester and @playwright/test (npm install --save-dev @gleanwork/mcp-server-tester@beta @playwright/test).
2. Find the tools to test and their input schemas: the server source, or await mcp.listTools() in a test.
3. Check playwright.config.ts for an mcpConfig (Step 1).

npx mst generate connects to a server, lets you call tools interactively, and writes the calls as a spec (default tests/generated.spec.ts) you can edit. npx @gleanwork/mcp-server-tester@beta init scaffolds a new project.

Step 1: Configure the server

Each Playwright project's use.mcpConfig says how to reach the server:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  reporter: [['list'], ['@gleanwork/mcp-server-tester/reporters/mcpReporter']],
  projects: [
    {
      name: 'local',
      use: {
        mcpConfig: {
          transport: 'stdio',
          command: 'node',
          args: ['./dist/server.js'],
          env: { LOG_LEVEL: 'warn' },
        },
      },
    },
    {
      name: 'staging',
      use: {
        mcpConfig: {
          transport: 'http',
          serverUrl: 'https://staging.example.com/mcp',
          auth: { accessToken: process.env.MCP_ACCESS_TOKEN },
        },
      },
    },
  ],
});

HTTP servers take serverUrl (not url) and optional headers. For auth: