---
title: Specdiff MCP Server
description: Expose Specdiff as tools for AI assistants through the Model Context Protocol.
url: https://pr-1-ff84656b4b8a.thally.app/specdiff/mcp
---

# Specdiff MCP Server

Expose Specdiff as tools for AI assistants through the Model Context Protocol.

The `@specdiff/mcp` package is a Model Context Protocol (MCP) server that exposes Specdiff's breaking-change detection as tools for AI assistants. Any MCP-compatible client -- such as Claude Desktop -- can call these tools to compare API specs, look up rules, and format reports.

The server is named `"specdiff"`, runs version `"0.1.0"`, and communicates over stdio transport.

## Installation

Run the server directly with `npx`:

```sh
npx -y @specdiff/mcp
```

Or install it globally:

```sh
npm install -g @specdiff/mcp
```

When launched, the server prints `specdiff-mcp listening on stdio` to stderr and waits for MCP messages on stdin/stdout.

## Configuration

### Claude Desktop

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "specdiff": {
      "command": "npx",
      "args": ["-y", "@specdiff/mcp"]
    }
  }
}
```

### Project-level configuration

Add a `.mcp.json` file to your project root:

```json
{
  "mcpServers": {
    "specdiff": {
      "command": "npx",
      "args": ["-y", "@specdiff/mcp"]
    }
  }
}
```

In both cases the server starts on demand when the client connects.

## Tools

The server registers four tools.

### `specdiff_compare`

Compares two JSON Schema or OpenAPI documents and returns a diff result.

**Input fields:**

| Field | Type | Required | Description |
|---|---|---|---|
| `beforePath` | `string` | no | File path to the "before" document, relative to the server working directory. |
| `afterPath` | `string` | no | File path to the "after" document, relative to the server working directory. |
| `before` | `string` | no | Inline JSON or YAML text for the "before" document. |
| `after` | `string` | no | Inline JSON or YAML text for the "after" document. |
| `kind` | `string` | no | `"auto"`, `"openapi"`, or `"json-schema"`. Defaults to `"auto"`. |
| `failOn` | `string` | no | `"breaking"`, `"warning"`, `"info"`, or `"none"`. Defaults to `"breaking"`. |
| `ignoreRules` | `string[]` | no | Rule codes to exclude from the result. |

Each side of the comparison needs either a path or inline text. You can mix approaches -- for example, load the "before" document from a file with `beforePath` and pass the "after" document as inline text with `after`.

**Output:** JSON containing the full `DiffResult` (with `changes`, `summary`, `maxSeverity`, and `kind` fields) plus two additional fields:

- `passed` -- `boolean`, `false` when the threshold is exceeded.
- `failOn` -- `string`, the threshold that was applied.

### `specdiff_explain_rule`

Returns detailed information about a single rule.

**Input:**

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | `string` | yes | The rule code to look up, e.g. `"endpoint-removed"`. |

**Output:** A `RuleInfo` JSON object with fields `code`, `defaultSeverity`, `title`, `description`, `remediation`, and `appliesTo`.

If the code is unknown, the tool returns an error: `No rule named "...". Call specdiff_list_rules for the catalogue.`

### `specdiff_list_rules`

Returns the full rule catalogue. Takes no input.

**Output:** A JSON array of `RuleInfo` objects covering all 45 rules.

### `specdiff_format`

Renders a `DiffResult` into a human-readable report.

**Input:**

| Field | Type | Required | Description |
|---|---|---|---|
| `result` | `object` | yes | A `DiffResult` object (as returned by `specdiff_compare`). |
| `format` | `string` | yes | `"text"` or `"markdown"`. |

**Output:** The formatted report as text content.

## Path security

File paths passed to `beforePath` or `afterPath` are resolved relative to the server's working directory. Any path that would escape that directory -- such as one containing `../` segments that resolve above the working directory -- is rejected with an error:

``Path "..." is outside the server's working directory (...); run specdiff-mcp from the project root.``

Start the MCP server from your project root so it can access spec files but not reach outside the project.

## Error handling

All tool errors are returned with `isError: true` and a text content message. Common error patterns:

- **Unknown rule code in `ignoreRules`:** `Unknown rule code in ignoreRules: "...".`
- **Unknown rule in `specdiff_explain_rule`:** `No rule named "...". Call specdiff_list_rules for the catalogue.`
- **Path escape:** `Path "..." is outside the server's working directory (...); run specdiff-mcp from the project root.`
- **General failure:** `specdiff_compare failed: ...` or `specdiff_format failed: ...`

## Programmatic usage

If you need to embed the Specdiff MCP server in a custom application or connect it to a non-stdio transport, use `createSpecdiffServer` from the package:

```ts
import { createSpecdiffServer } from "@specdiff/mcp";

const server = createSpecdiffServer({ cwd: "/path/to/project" });
```

The `createSpecdiffServer` function accepts an optional `SpecdiffServerOptions` object with a single field:

- `cwd` -- the working directory for resolving file paths. Defaults to `process.cwd()`.

The function returns an un-connected `McpServer` instance from `@modelcontextprotocol/sdk` with all four tools registered. You are responsible for connecting a transport of your choice.