A GitHub Action for diffing Model Context Protocol (MCP) server public interfaces between versions. Compares the current branch against a baseline to surface any changes to your server's exposed tools, resources, prompts, and capabilities.

Also available as a standalone CLI — see CLI Documentation or install with npx mcp-server-diff

MCP servers expose a public interface to AI assistants: tools (with their input schemas), resources, prompts, and server capabilities. As your server evolves, changes to this interface are worth tracking. This action automates public interface comparison by:

1. Building your MCP server from both the current branch and a baseline (merge-base, tag, or specified ref)
2. Querying both versions for their complete public interface (tools, resources, prompts, capabilities)
3. Generating a diff report showing exactly what changed
4. Surfacing results directly in GitHub's Job Summary

This is not about testing internal logic or correctness—it's about visibility into what your server advertises to clients.

Create .github/workflows/mcp-diff.yml in your repository:

name: MCP Server Diff

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
    tags: ['v*']

permissions:
  contents: read

jobs:
  mcp-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: SamMorrowDrums/mcp-server-diff@v2
        with:
          setup_node: true
          install_command: npm ci
          build_command: npm run build
          start_command: node dist/stdio.js

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    node_version: '22'
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_python: true
    python_version: '3.12'
    install_command: pip install -e .
    start_command: python -m my_mcp_server

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_go: true
    install_command: go mod download
    build_command: go build -o bin/server ./cmd/stdio
    start_command: ./bin/server

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_rust: true
    install_command: cargo fetch
    build_command: cargo build --release
    start_command: ./target/release/my-mcp-server

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_dotnet: true
    dotnet_version: '9.0.x'
    install_command: dotnet restore
    build_command: dotnet build -c Release
    start_command: dotnet run --no-build -c Release

If you need more control over environment setup (caching, specific registries, etc.), do your own setup before calling the action:

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

  - uses: actions/setup-node@v4
    with:
      node-version: '22'
      cache: 'npm'
      registry-url: 'https://npm.pkg.github.com'

  - uses: SamMorrowDrums/mcp-server-diff@v2
    with:
      install_command: npm ci
      build_command: npm run build
      start_command: node dist/stdio.js

Test both stdio and HTTP transports in a single run using the configurations input:

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    configurations: |
      [
        {
          "name": "stdio",
          "transport": "stdio",
          "start_command": "node dist/stdio.js"
        },
        {
          "name": "streamable-http",
          "transport": "streamable-http",
          "start_command": "node dist/http.js",
          "server_url": "http://localhost:3000/mcp"
        }
      ]

Either start_command (for stdio) or server_url (for HTTP) must be provided, unless using configurations.

When using configurations, each object supports:

When comparing against external servers (e.g., Docker images, remote services), use base_start_command to specify a different command for the baseline. This skips git checkout for that configuration and probes the specified server directly:

configurations: |
  [
    {
      "name": "compare-versions",
      "transport": "stdio",
      "start_command": "docker run -i ghcr.io/example/mcp-server:v2.0.0",
      "base_start_command": "docker run -i ghcr.io/example/mcp-server:v1.0.0"
    }
  ]

This is useful for:

• Version comparison: Compare a new release against the previous version
• Golden reference testing: Compare your local code against a known-good reference
• Cross-implementation testing: Compare different implementations of the same server
• Self-testing CI: Verify the action detects diffs by comparing two known-different servers

For HTTP transport, use base_server_url alongside base_start_command:

configurations: |
  [
    {
      "name": "http-comparison",
      "transport": "streamable-http",
      "start_command": "docker run -p 3000:3000 myserver:latest",
      "server_url": "http://localhost:3000/mcp",
      "base_start_command": "docker run -p 3001:3000 myserver:v1.0.0",
      "base_server_url": "http://localhost:3001/mcp"
    }
  ]

1. Baseline Detection: Determines the comparison ref:
   • For pull requests: merge-base with target branch
   • For tag pushes: previous tag (e.g., v1.1.0 compares against v1.0.0)
   • Explicit: uses compare_ref if provided
2. Build Baseline: Creates a git worktree at the baseline ref and builds the server
3. Build Current: Builds the server from the current branch
4. Conformance Testing: Sends MCP protocol requests to both servers:
   • initialize - Server capabilities and metadata
   • tools/list - Available tools and their schemas
   • resources/list - Available resources
   • prompts/list - Available prompts
5. Report Generation: Produces a Markdown report with diffs, uploaded as an artifact and displayed in Job Summary

The action queries the public interface of both server versions and compares the responses:

Differences appear as unified diffs in the report. Common changes include:

• New tools, resources, or prompts added
• Schema changes (new parameters, updated descriptions)
• Capability changes (new features enabled)
• Version string updates

Sometimes a configuration starts on one side of the comparison but fails to start on the other. The most common cause is a brand-new configuration that depends on a CLI flag or option that doesn't exist on the compare ref yet — for example a PR that introduces a new scoped server mode. On the compare ref the unknown flag is rejected and the server exits with something like MCP error -32000: Connection closed.

When exactly one side fails to start (and the other probes successfully), the action:

1. Reports a fail on the side that could not start, naming the version (current branch or compare ref) in a dedicated "🚫 missing on one side" section and a per-config callout, instead of an opaque probe error.
2. Diffs the working side against an empty baseline, so the entire surface of the new (or removed) configuration renders as added/removed — giving you a complete picture of what it exposes.
3. Does not trip fail_on_error. A one-sided startup failure is treated as a surface difference (config-missing), not a genuine probe error, so an introducing PR isn't failed for the expected "this config doesn't exist on the base ref yet" case. It still counts as a difference, so fail_on_diff will flag it if enabled.

When both sides fail to start, that is a genuine probe failure: it is reported as an error and trips fail_on_error (when enabled).

The default transport communicates with your server via stdin/stdout using JSON-RPC. For stdio, each configuration spawns a fresh server process:

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js

For HTTP servers, you typically want to start the server once and test multiple configurations against it. Use start_command at the configuration level—the action spawns the server, waits for startup, probes it, then terminates it after that configuration completes:

configurations: |
  [{
    "name": "http-server",
    "transport": "streamable-http",
    "start_command": "node dist/http.js",
    "server_url": "http://localhost:3000/mcp",
    "startup_wait_ms": 2000
  }]

Per-configuration server lifecycle: If your use case requires a fresh server instance per configuration (e.g., testing different flags or environment variables), include start_command in each configuration—each will get its own server process started and stopped.

Shared server for multiple configurations: If you want one HTTP server to handle multiple test configurations, use pre_test_command/post_test_command on the first/last configuration, or start the server in a prior workflow step:

configurations: |
  [
    {
      "name": "config-a",
      "transport": "streamable-http",
      "server_url": "http://localhost:3000/mcp",
      "pre_test_command": "node dist/http.js &",
      "pre_test_wait_ms": 2000
    },
    {
      "name": "config-b",
      "transport": "streamable-http",
      "server_url": "http://localhost:3000/mcp"
    },
    {
      "name": "config-c",
      "transport": "streamable-http",
      "server_url": "http://localhost:3000/mcp",
      "post_test_command": "pkill -f 'node dist/http.js' || true"
    }
  ]

Pre-deployed servers: For already-running servers (staging, production), omit lifecycle commands entirely:

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    install_command: 'true'
    transport: streamable-http
    server_url: https://mcp.example.com/api

On pull requests, the action automatically compares against the merge-base with the target branch. This shows exactly what changes the PR introduces.

When triggered by a tag push matching v*, the action finds the previous tag and compares against it:

on:
  push:
    tags: ['v*']

# v1.2.0 will automatically compare against v1.1.0

Specify any git ref to compare against:

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js
    compare_ref: v1.0.0

For release workflows where you want to ensure no API changes, use fail_on_diff:

- uses: SamMorrowDrums/mcp-server-diff@v2
  with:
    setup_node: true
    install_command: npm ci
    build_command: npm run build
    start_command: node dist/stdio.js
    compare_ref: v1.0.0
    fail_on_diff: true  # Action fails if any API changes are detected

The action produces:

1. Job Summary: Inline Markdown report in the GitHub Actions UI showing test results and diffs
2. Artifact: mcp-diff-report artifact containing MCP_DIFF_REPORT.md for download or further processing

When the MCP server's public interface hasn't changed between branches:

📊 Comparison:
  Current: HEAD
  Compare: abc1234 (v1.0.0)

🧪 Running diff...

📊 Phase 3: Comparing results...
📋 Configuration stdio: ✅ No changes

✅ No API Changes - All configurations match the baseline.

When changes are detected, the action shows a semantic diff with clear paths to each change:

📋 Configuration stdio: 3 change(s) found

The generated report shows exactly what changed using path notation:

--- base/tools.json
+++ branch/tools.json

+ tools[new_tool]: {"name": "new_tool", "description": "A newly added tool", ...}
- tools[old_tool].inputSchema.properties.name.description: "Old description"
+ tools[old_tool].inputSchema.properties.name.description: "Updated description"
- tools[calculator].inputSchema.properties.precision.type: "string"  
+ tools[calculator].inputSchema.properties.precision.type: "number"

--- base/resources.json
+++ branch/resources.json

+ resources[config://settings]: {"uri": "config://settings", "name": "Settings", ...}

Each line shows:

• + for additions (new tools, resources, or changed values)
• - for removals (deleted items or previous values)
• Full path to the change: tools[tool_name].inputSchema.properties.param.type

This makes it easy to see exactly what changed without wading through entire JSON dumps

name: MCP Server Diff

on:
  workflow_dispatch:
  pull_request:
    branches: [main]
  push:
    branches: [main]
    tags: ['v*']

permissions:
  contents: read

jobs:
  mcp-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: SamMorrowDrums/mcp-server-diff@v2
        with:
          setup_node: true
          install_command: npm ci
          build_command: npm run build
          configurations: |
            [
              {
                "name": "stdio",
                "transport": "stdio",
                "start_command": "node dist/stdio.js"
              },
              {
                "name": "streamable-http",
                "transport": "streamable-http",
                "start_command": "node dist/http.js",
                "server_url": "http://localhost:3000/mcp"
              }
            ]

• Check that start_command works locally
• Increase server_timeout for slow-starting servers
• Verify all dependencies are installed by install_command

• Ensure fetch-depth: 0 in your checkout step
• For new repositories, the first run may fail (no baseline exists)

• Verify server_url matches your server's listen address
• Ensure the server binds to 0.0.0.0 or 127.0.0.1, not just localhost on some systems
• Check firewall or container networking if running in Docker

The CLI lets you diff any two MCP servers directly from your terminal—useful for local development, CI pipelines, or comparing servers across different implementations.

# Run directly with npx (no install required)
npx mcp-server-diff --help

# Or install globally
npm install -g mcp-server-diff

# Compare two local stdio servers
npx mcp-server-diff -b "python -m mcp_server" -t "node dist/stdio.js"

# Compare local server vs remote HTTP endpoint
npx mcp-server-diff -b "go run ./cmd/server stdio" -t "https://mcp.example.com/api"

# Output formats
npx mcp-server-diff -b "..." -t "..." -o diff      # Raw diff hunks only
npx mcp-server-diff -b "..." -t "..." -o json      # Full JSON with details
npx mcp-server-diff -b "..." -t "..." -o markdown  # Formatted report
npx mcp-server-diff -b "..." -t "..." -o summary   # One-line summary (default)

For authenticated HTTP endpoints, pass headers with -H (target) or --base-header:

# Direct header value for target
npx mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \
  -H "Authorization: Bearer your-token-here"

# Read from environment variable (keeps secrets out of shell history)
export MCP_TOKEN="your-secret-token"
npx mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \
  -H "Authorization: Bearer env:MCP_TOKEN"

# Prompt for secret interactively (hidden input, named "token")
npx mcp-server-diff -b "./server" -t "https://api.example.com/mcp" \
  -H "Authorization: Bearer secret:token"

# Headers for both sides (e.g., comparing two authenticated servers)
npx mcp-server-diff \
  -b "https://api.example.com/v1/mcp" --base-header "Authorization: Bearer secret:v1token" \
  -t "https://api.example.com/v2/mcp" -H "Authorization: Bearer secret:v2token"

For complex comparisons or multiple targets, use a config file:

npx mcp-server-diff -c servers.json -o diff

{
  "base": {
    "name": "python-server",
    "transport": "stdio",
    "start_command": "python -m mcp_server"
  },
  "targets": [
    {
      "name": "typescript-server",
      "transport": "stdio",
      "start_command": "node dist/stdio.js"
    },
    {
      "name": "remote-server",
      "transport": "streamable-http",
      "server_url": "https://mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  ]
}

Header value patterns:

• Bearer your-token — literal value
• Bearer env:VAR_NAME — read from environment variable
• Bearer secret:name — prompt once for "name", reuse if used multiple times

Version 3.0 is a maintenance release that refreshes the dependency tree and prepares the probe for the upcoming MCP draft spec.

Dependency upgrades (breaking only at the install layer)

• zod v3 → v4 (signature of z.record now requires explicit key + value schemas)
• undici v6 → v8 (also updates the overrides block, resolving the v6 WebSocket advisories)
• diff v8 → v9
• @actions/core, @actions/exec, @actions/io v1 → v3
• eslint / @eslint/js v9 → v10, typescript v5 → v6, jest / @types/jest v29 → v30
• @types/node v22 → v24 (the action and CLI are tested on Node 22 + 24)
• @vercel/ncc 0.38 → 0.44

Dropped support: Node.js 20. Node 20 reached end-of-life on 2026-04-30 and undici v8 requires Node 22+. The action and CLI now require Node.js 22 or newer; the action defaults to Node 22 when setup_node: true is supplied without an explicit node_version.

If you consume mcp-server-diff as a GitHub Action or via npx, nothing in your workflow should change.

MCP draft-spec forward-compat

The probe now strips the ttlMs and cacheScope cache hints (CacheableResult, SEP-2461) from the top level of tools/list, prompts/list, resources/list, and resources/templates/list results before snapshotting. These freshness hints are intended to vary between runs, so stripping them keeps diffs focused on real interface changes. Nested ttlMs / cacheScope fields (e.g. inside a tool description) are preserved.

The initialize snapshot is captured from whichever handshake path the server actually supports — see Cross-spec-version diffing for details. Servers on the draft spec (SEP-2575) are probed statelessly via server/discover; pre-draft servers continue to use the legacy initialize handshake via @modelcontextprotocol/sdk. Both flow into the same canonical initialize snapshot file.

A common situation during the draft-spec rollout is that the base ref runs against MCP spec 2025-06-18 or 2025-11-25 while the branch runs against the draft. The tool is designed so that a server upgrading its SDK without changing its public surface produces a clean diff.

What gets normalized away before snapshotting:

• CacheableResult hints — top-level ttlMs / cacheScope on tools/list, prompts/list, resources/list, and resources/templates/list (SEP-2461).
• _meta protocol plumbing — a specific, exact-key denylist is stripped from every _meta object, at any depth: io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities, io.modelcontextprotocol/subscriptionId, io.modelcontextprotocol/logLevel. An emptied _meta is dropped entirely. We do not strip by prefix: the io.modelcontextprotocol/* namespace is reserved by the spec but is also where official extensions live (MCP Apps' _meta.ui, Tasks' io.modelcontextprotocol/related-task, etc.) — those surfaces are exactly what this tool exists to diff, so they round-trip untouched.
• W3C trace context inside _meta — traceparent, tracestate, and baggage (transport-injected for OTel propagation) are stripped from _meta.
• Tool annotation default hints — ToolAnnotations fields are dropped when they equal their spec defaults (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so a server that emits explicit defaults compares equal to one that omits them. Important when an SDK toggles omitempty between versions (e.g. go-sdk v1.6→v1.7 dropped it on ReadOnlyHint/IdempotentHint and would otherwise show every tool as "changed"). An emptied annotations object is dropped entirely.
• initialize envelope churn — protocolVersion and capabilities.experimental are excluded from the initialize snapshot body. The negotiated protocol version is captured separately and surfaced by the reporter (see below).
• Endpoint names are canonicalized — see CANONICAL_SNAPSHOT_NAMES in src/probe.ts. The probe tries the stateless server/discover path first (SEP-2575, SEP-2243) so a server on the draft spec is probed at its own newest spec version; on any failure it falls back to the legacy initialize handshake via @modelcontextprotocol/sdk. Both flow into the same initialize snapshot file, so a spec upgrade shows up as a content diff on one file, not a "removed + added" pair. The reporter still surfaces "Protocol version changed from X to Y" via a banner. Note that fields like instructions and capabilities are NOT normalized away even though they may differ between paths — those are real public-interface signals. For example, go-sdk v1.7.0-pre.1 emits instructions on initialize but omits it from server/discover; this is spec-conformant (instructions is optional on both result shapes) but is still a public-interface difference clients adopting discover observe, so it surfaces in the diff.

What is not normalized (intentionally):

• serverInfo.version (the SDK version is a legitimate signal worth tracking).
• Nested ttlMs / cacheScope that live inside a tool/prompt/resource definition (those would be part of the public surface, not envelope hints).
• Any _meta key not on the exact denylist above — including the entire MCP Apps surface (_meta.ui and friends, SEP-1865) and vendor extensions under non-reserved namespaces (x.acme/*, etc.).

When the base and branch probes negotiate different MCP protocol versions, the report (and the PR summary) emit a banner like:

ℹ️ MCP protocol version changed: 2025-11-25 → draft. Protocol-level plumbing is normalized away; any diff below reflects real public-surface changes.

If the public surface is identical the diff is empty even when the protocol version moved — the banner is the only signal.

MIT License. See LICENSE for details.

Contributions are welcome. Please read CONTRIBUTING.md for guidelines.

• Model Context Protocol Specification
• MCP TypeScript SDK
• MCP Python SDK
• MCP Go SDK

Working examples of this action in various languages:

For a production example, see github-mcp-server.