Skip to main content
Glama
specmatic

Specmatic MCP Server

Official
by specmatic
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Specmatic MCP Server

Docker Pulls npm version

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)

Related MCP server: swagger-mcp-server

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

  1. Install the package globally (optional, for easier access):

    npm install -g specmatic-mcp

  2. Open your project in VS Code as a workspace

  3. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → MCP: Add server

  4. Choose transport protocol: stdio

  5. Enter command:

    npx specmatic-mcp

  6. Set server ID: specmatic

  7. Choose scope: Global or Workspace

Other MCP Clients

Add to your mcp.json configuration:

{
  "servers": {
    "specmatic": {
      "command": "npx",
      "args": ["specmatic-mcp"],
      "env": {}
    }
  }
}

Docker Alternative

Claude Code

claude mcp add-json specmatic '{"command":"docker","args":["run","--rm","-i","--network=host","-v","'$(pwd)/reports':/app/reports","specmatic/specmatic-mcp:latest"],"env":{}}'

Note: If you encounter path resolution issues with $(pwd), replace it with your absolute project path:

claude mcp add-json specmatic '{"command":"docker","args":["run","--rm","-i","--network=host","-v","/path/to/your/project/reports:/app/reports","specmatic/specmatic-mcp:latest"],"env":{}}'

VSCode

  1. Make sure Docker Desktop is running

  2. Open your project in VS Code as a workspace (single-folder or multi-root as needed).

  3. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and search for MCP: Add server, then press Enter

  4. Choose transport protocol as stdio

  5. ⚠️ CRITICAL: Enter the command to run the MCP server - YOU MUST REPLACE <REPLACE_WITH_YOUR_PROJECT_PATH> with your actual project path:

    Template:

    docker run --rm -i --network=host -v <REPLACE_WITH_YOUR_PROJECT_PATH>/reports:/app/reports specmatic/specmatic-mcp:latest

    Examples:

    # macOS/Linux example:
docker run --rm -i --network=host -v /Users/yourname/projects/my-api-project/reports:/app/reports specmatic/specmatic-mcp:latest

# Windows example:
docker run --rm -i --network=host -v C:\Users\yourname\projects\my-api-project\reports:/app/reports specmatic/specmatic-mcp:latest

  6. Set the server ID to specmatic-mcp.

  7. Choose installation scope: Global (available everywhere) or Workspace (just this project).

  8. Verify the server: Make sure that Specmatic MCP is listed without errors in the MCP servers panel and then request your Copilot Agent to run contract tests, resiliency tests, or start a mock server in natural language.

Other MCP Clients (Docker)

For Cursor, GitHub Copilot, or other MCP clients, add to your mcp.json configuration:

⚠️ IMPORTANT: Replace <REPLACE_WITH_YOUR_PROJECT_PATH> with your actual project path.

{
  "servers": {
    "specmatic": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "-v",
        "<REPLACE_WITH_YOUR_PROJECT_PATH>/reports:/app/reports",
        "specmatic/specmatic-mcp:latest"
      ],
      "env": {}
    }
  }
}

Path Examples:

  • macOS/Linux: /Users/yourname/projects/my-api-project/reports:/app/reports

  • Windows: C:\Users\yourname\projects\my-api-project\reports:/app/reports

Important: Host Network Mode

The --network=host flag is required for:

  • Testing localhost APIs: Allows the container to access APIs running on your host machine (e.g., http://localhost:3000)

  • Mock server access: Enables mock servers to be accessible from your host system for frontend development

  • Port binding: Ensures mock servers on specific ports are reachable from outside the container

Security Note: Host networking gives the container access to your host's network interfaces. Only use this with trusted images.

Choosing the Right Method

Use npm package (recommended) for easier setup and faster performance.

Use Docker if you prefer not to install Node.js and Java locally on your system.

Tool Availability by Environment

npm Package:

  • ✅ Contract Testing (run_contract_test)

  • ✅ Resiliency Testing (run_resiliency_test)

  • ✅ Mock Server Management (manage_mock_server)

  • ✅ Backward Compatibility Check (backward_compatibility_check)

Docker:

  • ✅ Contract Testing (run_contract_test)

  • ✅ Resiliency Testing (run_resiliency_test)

  • ✅ Mock Server Management (manage_mock_server)

  • ❌ Backward Compatibility Check (requires direct git repository access)

Reports and Output

npm Package:

  • JUnit XML reports generated in ./reports/ directory (relative to where you run the command)

  • Direct filesystem access for easy report analysis

  • Reports persist after command completion

Docker:

  • JUnit XML reports generated in volume-mounted ./reports/ directory on host

  • Requires volume mounting: -v "$(pwd)/reports:/app/reports"

  • Reports accessible on host filesystem

Both methods provide:

  • Console output with immediate feedback and summaries

  • Detailed test results and timing information in JUnit XML format

  • Structured error reporting and stack traces

Usage Examples

Simply interact with your AI coding agent using natural language. The agent will call the appropriate MCP tools based on your requests. All detailed examples and output formats are available in the project's AGENTS.md file for reference. CLAUDE.md is kept as a thin wrapper for Claude Code compatibility.

🚀 Try the Complete Example

Explore a full-stack application built with Specmatic MCP as guard rails:

https://github.com/specmatic/specmatic-mcp-sample

This sample project demonstrates how to build an entire frontend and backend application using Specmatic MCP for contract testing, API mocking, and resiliency validation.

Support

For issues, questions, or feature requests, please open an issue on GitHub.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Available Tools

3 tools
manage_mock_serverA

Manage Specmatic mock servers - start, stop, or list running servers for frontend development. Supports complete mock server lifecycle management.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe action to perform: 'start' creates a new server, 'stop' terminates a server, 'list' shows running servers
openApiSpecNoThe OpenAPI specification content (YAML or JSON) - required for 'start' command
portNoPort number for the mock server - required for 'start' and 'stop' commands
specFormatNoFormat of the OpenAPI spec - used with 'start' commandyaml

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes lifecycle actions but lacks disclosure of side effects, permissions required, or error behaviors. With no annotations, the description carries full burden and provides only basic operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences covering purpose and scope with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for basic understanding but missing output expectations and error handling details. With no output schema, description should explain return values or success/failure signals.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters with descriptions, but the description adds value by clarifying conditional requirements (e.g., openApiSpec and port needed for start command) beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it manages Specmatic mock servers with specific actions (start, stop, list) for frontend development. Distinguishes from sibling tools (run_contract_test, run_resiliency_test) which are different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for frontend development but does not explicitly state when to use this tool vs siblings or when not to use. No exclusion criteria or alternative suggestions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_contract_testB

Run Specmatic contract tests against an API using OpenAPI specification

ParametersJSON Schema
NameRequiredDescriptionDefault
openApiSpecYesThe OpenAPI specification content (YAML or JSON)
apiBaseUrlYesThe base URL of the API to test against
specFormatNoFormat of the OpenAPI specyaml

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full behavioral disclosure burden. It only states the action but does not reveal any behavioral traits such as whether it is read-only, what happens on failure, or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the tool's purpose with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the basic purpose, it lacks information about output (e.g., test results format, success/failure) and does not mention what the agent should expect after execution. Given no output schema, this is a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning to what the schema already provides (parameters are named openApiSpec, apiBaseUrl, specFormat).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as running Specmatic contract tests against an API using an OpenAPI spec. It uses specific verb ('Run') and resource ('Specmatic contract tests'), and the name and sibling tools (manage_mock_server, run_resiliency_test) make its purpose distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tools (manage_mock_server, run_resiliency_test). It does not mention prerequisites or scenarios where contract testing is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_resiliency_testB

Run Specmatic resiliency tests with boundary condition testing against an API using OpenAPI specification. This enables SPECMATIC_GENERATIVE_TESTS to test how the API handles contract-invalid requests

ParametersJSON Schema
NameRequiredDescriptionDefault
openApiSpecYesThe OpenAPI specification content (YAML or JSON)
apiBaseUrlYesThe base URL of the API to test against
specFormatNoFormat of the OpenAPI specyaml

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates the tool sends invalid requests (boundary condition testing) but provides no detail on side effects, permissions needed, or whether it is safe to run. With no annotations, more transparency would be beneficial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, but the second sentence is somewhat redundant. It is reasonably concise and front-loaded with the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, and the description does not mention what the tool returns. Given the complexity of a resiliency test, this is a significant gap. Also lacks connection to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter. The description adds the overall purpose but does not extend meaning for individual parameters beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs Specmatic resiliency tests with boundary condition testing, specifying it tests how the API handles contract-invalid requests. However, it does not explicitly distinguish from sibling tool 'run_contract_test', which may also test contract conformance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'run_contract_test' or 'manage_mock_server'. No prerequisites or context for invocation are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool targets a distinct aspect of Specmatic: mock server lifecycle, contract testing, and resiliency testing. No overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with underscores: manage_mock_server, run_contract_test, run_resiliency_test.

Tool Count5/5

Three tools is well-scoped for a focused server covering essential functionality without being too few or too many.

Completeness4/5

Covers mock server management, contract testing, and resiliency testing. Minor gap: no tool for loading/configuring OpenAPI specs, but core workflows are complete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/specmatic/specmatic-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server