Specmatic MCP Server

A Model Context Protocol (MCP) server that exposes Specmatic’s capabilities—including API Contract Testing, API Resiliency Testing, and API mocking—to AI coding agents.

What You Can Do

Interact with your AI coding agent using natural language to:

"Run contract tests against my API at https://api.example.com using this OpenAPI spec: [paste spec]"
"Start a mock server on port 9000 using this spec: [paste spec]"
"Run resiliency tests to check error handling with @products-api.yaml spec"
"Check for breaking changes in my API spec at /path/to/openapi.yaml compared to main branch"
"List all running mock servers"
"Stop the mock server on port 9000"

Available Tools

run_contract_test

Validates API implementations against OpenAPI specifications by running contract tests.

• Input: OpenAPI spec, API base URL, spec format (yaml/json)
• Output: Test results with pass/fail status and detailed failure information
• Use case: Ensure your API implementation matches the contract specification

run_resiliency_test

Tests API resilience by sending boundary condition and invalid requests.

• Input: OpenAPI spec, API base URL, spec format (yaml/json)
• Output: Enhanced testing results including edge case validation
• Use case: Verify proper error handling and API robustness

manage_mock_server

Complete mock server lifecycle management for frontend development.

• Subcommands: start, stop, list
• Features: Port management, multiple concurrent servers, automatic cleanup
• Use case: Generate mock APIs from OpenAPI specs for frontend development

backward_compatibility_check (npm package only)

Checks for breaking changes in OpenAPI specifications using git comparison.

• Input: OpenAPI spec file path, git branch comparison, repository directory
• Output: Backward compatibility analysis with breaking change detection
• Use case: Validate API changes don’t break existing clients before deployment
• Prerequisite: Requires git version control - Specmatic compares current spec with previous version to identify changes
• Availability: Only available when using the npm package (not available in Docker due to git repository access requirements)

Prerequisites

• MCP-compatible coding environment (Claude Code, VSCode with MCP extension, Cursor, GitHub Copilot, etc.)

For npm package (recommended):

• Node.js stable (nvm use stable)
• Java Runtime Environment (JRE)
• Git (required for backward compatibility checking)

For Docker:

• Docker installed and running

Setup

npm Package (Recommended)

Claude Code

claude mcp add specmatic npx specmatic-mcp

VSCode