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

> Source: <https://dev.to/wozaisuzhou/testing-mcp-servers-used-to-be-a-pain-here-is-how-to-test-them-with-zero-configuration-58j6>
> Published: 2026-08-10 00:54:40+00:00

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:

``` js
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!