Skip to content

Getting started

Lint a saved snapshot

Pass a saved tools/list result or an mcp-lint snapshot with --file:

npx https://superintelligenceco.github.io/pkg/mcp-lint.tgz --file tools.json

The last lines of the report show the score, the grade, and whether the run passed, for example:

Score 50/100  Grade F  (6 errors, 10 warnings, 3 info)
Failed: score is below the minimum of 70.

The exit code is 1 because the score is below the default minimum of 70.

Lint a running server

Put a stdio server's command after --:

mcp-lint -- npx -y @modelcontextprotocol/server-everything

For a remote server, pass --url. mcp-lint tries Streamable HTTP first and falls back to HTTP+SSE:

mcp-lint --url https://mcp.example.com/mcp -H "Authorization: Bearer $MCP_TOKEN"

Gate a pull request

Save a snapshot once, commit it, and lint it in CI without starting the server:

mcp-lint --save mcp-snapshot.json -- node dist/server.js
mcp-lint --file mcp-snapshot.json --min-score 85 --sarif mcp-lint.sarif

In GitHub Actions, install the CLI, lint the server, and upload the SARIF report to code scanning:

- run: npm install -g https://superintelligenceco.github.io/pkg/mcp-lint.tgz
- run: mcp-lint --min-score 80 --sarif mcp-lint.sarif -- node dist/server.js
- if: always()
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: mcp-lint.sarif
    category: mcp-lint

Configure rules

Put a .mcp-lint.json in the working directory:

{
  "minScore": 80,
  "rules": { "naming/inconsistent-style": "off" },
  "ignoreTools": ["debug_dump"]
}

Unknown keys and unknown rule IDs are errors, so a typo cannot silently disable a rule.

Use the library

Add the package to your project with npm install https://superintelligenceco.github.io/pkg/mcp-lint.tgz, then:

import { lint, readSnapshotFile } from "@superintelligenceco/mcp-lint";

const { snapshot } = readSnapshotFile("tools.json");
const result = lint(snapshot);
console.log(result.score, result.grade, result.findings.length);