Testing MCP Servers Used to Be a Pain. Here is How to Test Them with Zero Configuration.

When building Model Context Protocol (MCP) servers or AI agents that consume them, traditional API testing tools fall short. An MCP server isn't just a basic REST endpoint—it's a dynamic interface exposed to non-deterministic LLMs through stdio, HTTP, or SSE transports.

Testing tool schemas, transient network failures, and agent behaviors usually requires writing a mountain of boilerplate.

I built bubblemcp-test-kit to eliminate that friction: no backend accounts, no complex test setup, and zero instrumentation required.

What is bubblemcp-test-kit?

bubblemcp-test-kit is a lightweight, standalone testing toolkit designed specifically for MCP server developers and AI agent engineers.

Key features include:

Transport Agnostic: Work with stdio, HTTP, or SSE behind a unified API.

Fluent Assertions: Native matchers tailored for MCP response structures and JSON Schemas.

Mocking & Replay: Fabricate tool outputs locally or record real server runs to replay in offline CI environments.

Agent Trace & Fault Injection: Test if your AI agent calls tools in the right order and handles errors properly.

Quickstart Example

You can run a complete mock test suite without spinning up a live server:

import {
  createMockMcpClient,
  expectMcp,
  validateAgainstSchema,
  withRecording,
  createReplayClient,
} from 'bubblemcp-test-kit'

// 1. Define your tool contract
const healthCheckTool = {
  name: 'health_check',
  description: 'Reports service health',
  inputSchema: {
    type: 'object',
    properties: { service: { type: 'string' } },
    required: ['service'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      service: { type: 'string' },
      status: { type: 'string', enum: ['ok', 'degraded', 'down'] },
      latencyMs: { type: 'number' },
    },
    required: ['service', 'status', 'latencyMs'],
  },
}

// 2. Set up a mock MCP client
const mock = createMockMcpClient({ tools: [healthCheckTool] })
mock.mockTool('health_check').resolves({ service: 'weather', status: 'ok', latencyMs: 12 })
mock.mockTool('flaky_tool').rejects('rate limited')

// 3. Chain fluent assertions
const result = await mock.callTool('health_check', { service: 'weather' })

expectMcp(result)
  .toBeValidMcpResponse()
  .not.toBeError()
  .toContainText('weather')
  .toMatchOutputSchema(healthCheckTool)

// 4. Validate schema violations locally
const badPayload = { service: 'weather', status: 'invalid-status', latencyMs: 'slow' }
const validation = validateAgainstSchema(badPayload, healthCheckTool.outputSchema)
console.log('Schema valid?', validation.valid) // false

// 5. Record & Replay for CI
const FIXTURE = './fixtures/health-check.json'
const recording = withRecording(mock, FIXTURE)
await recording.callTool('health_check', { service: 'weather' })

// Replay offline inside CI pipelines
const replay = await createReplayClient(FIXTURE)
const replayed = await replay.callTool('health_check', { service: 'weather' })
expectMcp(replayed).toBeValidMcpResponse()

Instant CLI Smoke Testing

If you just want to run an instant health check on an existing MCP server, use the CLI directly:

npx bubblemcp-test-kit test --url http://localhost:3000/mcp --security

It discovers your tools, validates outputs against declared JSON Schemas, scans for prompt poisoning or credential leaks, and outputs a formatted pass/fail report.

Check out the full repository and let me know what you think in the comments!