specmatic

Specmatic MCP Server exposes Specmatic’s API Contract Testing, API Resiliency Testing, and API Mocking capabilities to AI agents. You can interact with the server using natural language prompts to run contract tests against an API, start and manage mock servers from OpenAPI specs, perform resiliency tests to validate error handling, and check for breaking changes between your local spec and a reference branch. The server provides tools such as run_contract_test, run_resiliency_test, manage_mock_server, and (when using the npm package) backward_compatibility_check. For example, you can ask the agent to run contract tests against your API at a given URL with a provided spec, start a mock server on a specific port, or list and stop active mock servers.

To use these tools, ensure the MCP client is connected to the specmatic MCP server. You’ll typically reference the available tools by name (e.g., run_contract_test, run_resiliency_test, manage_mock_server) and provide inputs like the OpenAPI spec, the API base URL, and the spec format (yaml or json). The backward_compatibility_check tool is available when you install via the npm package and is not available in Docker due to git access requirements.

Prerequisites:

• MCP-compatible environment (e.g., Claude Code, VSCode MCP extension, Cursor, GitHub Copilot, etc.)
• Node.js and npm (for the npm package) or Docker (for the Docker deployment)
• Git (for backward compatibility checking with the npm package)

Option A — Install via npm package (recommended):

1. Install Node.js and npm (follow your OS guidelines; ensure stable version is used).
2. Install the npm package globally (optional) and/or set up your MCP client:
   • npm install -g specmatic-mcp
3. Start the MCP server via the npm-based command from your MCP client configuration, for example:
   • npx specmatic-mcp
4. In your MCP client, add a server entry similar to: { "servers": { "specmatic": { "command": "npx", "args": ["specmatic-mcp"], "env": {} } } }

Option B — Run via Docker:

1. Ensure Docker is installed and running.
2. Run the Docker image for Specmatic MCP: docker run --rm -i --network=host -v <path-to-your-project>/reports:/app/reports specmatic/specmatic-mcp:latest
3. In your MCP client, add a server entry similar to the Docker configuration: { "servers": { "specmatic": { "command": "docker", "args": [ "run", "--rm", "-i", "--network=host", "-v", "<REPLACE_WITH_YOUR_PROJECT_PATH>/reports:/app/reports", "specmatic/specmatic-mcp:latest" ], "env": {} } } }

Prerequisites vary by method:

• npm package: Node.js, npm, Java Runtime Environment (JRE), and Git if using backward compatibility checks
• Docker: Docker installed and running

Tips and notes:

• The backward_compatibility_check tool is available only when using the npm package and requires Git access to compare specs against a repository history.
• For local testing (localhost APIs), the Docker host network mode (--network=host) is often required so mock servers and local APIs are accessible from the container.
• When using Docker, mount a reports directory to persist JUnit XML reports generated at ./reports inside the container.
• If you encounter path resolution issues with volume mappings, use absolute paths for the host side of the mount.
• The MCP setup supports multiple servers; you can add several entries under the mcp.json configuration to manage different specs or ports concurrently.
• Ensure your OpenAPI spec format (yaml/json) is correctly specified when invoking tools like run_contract_test and run_resiliency_test.