mcp-lint

mcp-lint

Lint MCP server tool schemas, then check whether an agent can recover when a tool fails.

Proof page, with a live bench: mcp-lint-alpha.vercel.app

MCP servers expose tool schemas consumed by Claude, Cursor, Gemini, VS Code Copilot, Windsurf, Cline, OpenAI Agents SDK, and Continue.dev. Each client has different JSON Schema support and quirks — a schema that works in Claude may silently break in Cursor or OpenAI. mcp-lint catches these issues before your users do.

This repository is 1.0.4. Install it with npx mcp-lint@1.0.4. npm 1.0.3 is the previous registry release. npm 1.0.1 and npm 1.0.2 were not published. Design notes: PRODUCT.md, ROADMAP.md, ARCHITECTURE.md, SECURITY.md, RELEASE.md. Those files describe the current code. They are not extra commands.

$ npx mcp-lint check tools.json

search-tool ✖ Schema node at "inputSchema.properties.query" has required: false which is not valid JSON Schema. inputSchema.properties.query [no-required-false] ⚠ Parameter "limit" in tool "search-tool" is missing a description. inputSchema.properties.limit [description-exists]

1 error, 1 warning Next: mcp-lint explain no-required-false mcp-lint fix tools.json --dry-run

---

Installation

# In a repo that already has tools.json

npx mcp-lint

Or point at a file

npx mcp-lint check tools.json

Global

npm install -g mcp-lint

Per-project dev dependency

npm install --save-dev mcp-lint

---

Quick Start

# Look in this directory, and one level down, for tools.json, tools.yaml,

tools.yml, mcp-tools.json, mcp-tools.yaml, or mcp-tools.yml

npx mcp-lint

Check a JSON or YAML file

mcp-lint check tools.json

See compatibility across all clients at a glance

mcp-lint compat tools.json

Learn what a rule does

mcp-lint explain openai/no-additional-properties

Auto-fix what can be fixed

mcp-lint fix tools.json --in-place

Generate a config file

mcp-lint init

Run as an MCP server

mcp-lint-server

Score whether a tool failure tells the agent which tool to call next

mcp-lint recover examples/recover/bad-credential.json

Lint the stdio servers already configured for Cursor, Claude, and VS Code

mcp-lint check --installed

Save a live tool list, then fail CI when a later snapshot gets worse

mcp-lint snapshot -o tools.json --server stdio -- node server.js mcp-lint diff tools.json tools.next.json

---

mcp-lint compat — Compatibility Matrix

See exactly which tools work with which clients:

$ mcp-lint compat tools.json

claude cursor gemini vscode windsurf cline openai continue search-tool ✓ ✗ ✓ ✓ ✓ ✓ ✓ ✓ file-reader ✓ ✓ ✗ ✓ ✓ ✓ ✓ ✗ database-query ✓ ✓ ✓ ✓ ✓ ✓ ✗ ✓

2 tools have compatibility issues. Run mcp-lint check for details.

mcp-lint compat tools.json --format markdown         # for PRs and GitHub Step Summary

mcp-lint compat tools.json --format json # machine-readable mcp-lint compat tools.json --client openai # single client column mcp-lint compat --server stdio -- node server.js

---

mcp-lint explain — Rule Documentation

$ mcp-lint explain openai/no-additional-properties

Rule: openai/no-additional-properties Severity: error Clients: openai Fix: review mcp-lint fix lists this and does not write it.

Description OpenAI Agents SDK strict mode requires additionalProperties: false on the root inputSchema.

Why OpenAI's strict function calling mode rejects schemas that don't explicitly set additionalProperties: false at the root level.

Bad example { "type": "object", "properties": { "q": { "type": "string" } } }

Good example { "type": "object", "properties": { "q": { "type": "string" } }, "additionalProperties": false }

Change Add "additionalProperties": false to the root inputSchema.

---

CLI Reference

mcp-lint check [input]

mcp-lint check tools.json

Output formats

mcp-lint check tools.json --format terminal # default, colored output mcp-lint check tools.json --format json # machine-readable (CI/CD) mcp-lint check tools.json --format markdown # for PRs and GitHub summaries

Filters

mcp-lint check tools.json --clients claude,cursor,openai # only these clients' rules mcp-lint check tools.json --severity error # errors only mcp-lint check tools.json --quiet # same as --severity error mcp-lint check tools.json --ignore "debug-tool,internal-tool"

Config

mcp-lint check tools.json --config path/to/.mcplintrc.json mcp-lint check tools.json --no-color

Quality score (0–100 per tool with A-F grades)

mcp-lint check tools.json --score

Watch mode (re-lints on file change)

mcp-lint check tools.json --watch

Live servers

mcp-lint check --server stdio -- node my-server.js mcp-lint check --server stdio -- python my_server.py arg1 arg2 mcp-lint check --server sse --url http://localhost:3000/sse

Exit codes:

mcp-lint report

Writes the versioned audit report for one tools file. check --format json still prints the diagnostic array. report --format json prints MCPAuditReport.

mcp-lint report tools.json

mcp-lint report tools.json --format sarif --output results.sarif mcp-lint report tools.json --format html --output report.html mcp-lint report tools.json --format markdown

Formats are terminal, json, markdown, sarif, and html. The HTML file has inline CSS and no script. Token totals are a local chars / 4 estimate. The compatibility section is filled from that same lint. A cell is measured or not_observed. An empty tool list leaves the section not run. Recovery, preflight, and live inspection stay marked as not run. When the run has no schema errors, the report says: "No schema errors in this run. Recovery, preflight, and live inspection were not measured."

mcp-lint report tools.json --baseline audit.baseline.json

mcp-lint report tools.json --update-baseline audit.baseline.json

--baseline exits 1 when the stable snapshot differs. The snapshot pins generatedAt and keeps tool.version. Pass either --baseline or --update-baseline, not both. Exit 1 when the report contains an error, or when the file cannot be read.

mcp-lint catalog

Lists resources and prompts from one live server, then lints that list. It does not read installed configs and it does not call a tool. An empty or repeated URI, an empty resource name, an empty or repeated prompt name, and an empty or repeated argument name are errors and exit 1. A repeated resource display name, and a missing description, are warnings and do not. explain prints the rule. The fix class is manual: the command does not rewrite the server.

mcp-lint catalog --server stdio -- node server.js

mcp-lint catalog --server http --url https://example.com/mcp --format json

--server is stdio, sse, or http. Remote transports need --url. --timeout, --max-items, and --max-bytes bound each list. A method the server does not implement is unsupported and exits 0. Any other list failure exits 1. A lint error also exits 1. Usage errors exit 2. --format is terminal or json. JSON adds a findings array to the list. The array is empty when the list is clean.

---

mcp-lint diff

Compare lint results between two versions of your schema — useful in CI to catch regressions.

mcp-lint diff tools-v1.json tools-v2.json

mcp-lint diff tools-v1.json tools-v2.json --format markdown >> $GITHUB_STEP_SUMMARY mcp-lint diff tools-v1.json tools-v2.json --format json

Exit codes: 0 = no new errors introduced, 1 = new errors found, 2 = error

---

mcp-lint check --installed

Reads the MCP configs already on this machine and lints each local stdio server. Nothing is uploaded. Remote URLs are skipped unless you pass --remote.

mcp-lint check --installed

mcp-lint check --from .cursor/mcp.json mcp-lint check --from .mcp.json --timeout 10000 --strict

Looked-up files:

--strict also exits 1 when a configured server fails to start. Without it, a start failure is printed and the exit code follows the schema errors. If two started servers expose the same tool name, both reports include tool-name/server-collision.

---

mcp-lint snapshot

Writes the live tools/list as a stable JSON file. Commit that file and compare it with diff when the server changes. diff exits 1 when the new file introduces an error the old file did not have.

mcp-lint snapshot -o tools.json --server stdio -- node server.js

mcp-lint snapshot -o tools.json --server http --url http://127.0.0.1:3000/mcp mcp-lint diff tools.json tools.next.json

---

mcp-lint fix [input]

Writes fixes marked safe. review and manual fixes are printed by --dry-run and left in the file. mcp-lint does not invent titles, descriptions, or hints.

mcp-lint fix tools.json                            # fixed output to stdout

mcp-lint fix tools.json --output fixed-tools.json # write to file mcp-lint fix tools.json --in-place # overwrite original mcp-lint fix tools.json --dry-run # show what would be fixed mcp-lint fix tools.json --rules no-required-false,no-empty-enum # specific rules only

---

mcp-lint init

Creates a default .mcplintrc.json in the current directory.

mcp-lint init          # fails if file already exists

mcp-lint init --force # overwrite existing

---

Rules

Universal (all clients)

| max-depth | 🟡 warning | ❌ | Schema nesting deeper than 5 levels