@samsec/mcpx is a command-line tool that lints and inspects MCP servers. It calls the MCP Playground public API and exits with a non-zero code when issues are found — making it a drop-in quality gate for GitHub Actions, GitLab CI, or any CI system.
Run without installing
npx @samsec/mcpx lint https://your-server.com/mcpGlobal install
npm install -g @samsec/mcpx
mcpx --versionLint a server schema and return a grade (A–F), score, token estimate, and actionable issues. Exits 0 on pass, 1 on fail, 2 if unreachable.
# Default — fail on errors only
mcpx lint https://your-server.com/mcp
# Fail on warnings too
mcpx lint https://your-server.com/mcp --fail-on warnings
# Require at least a B grade
mcpx lint https://your-server.com/mcp --min-grade B
# Fail if token footprint exceeds 5,000 tokens
mcpx lint https://your-server.com/mcp --token-budget 5000
# Machine-readable JSON (pipeable)
mcpx lint https://your-server.com/mcp --format json | jq '.grade'
# Silent — exit code only (useful in scripts)
mcpx lint https://your-server.com/mcp --quiet && echo "passed"--fail-on <level>Fail on errors or warningserrors--min-grade <grade>Fail if grade is below A, B, C, D, or F—--token-budget <n>Fail if total token estimate exceeds N—--format jsonOutput raw JSON, no spinner—--quietNo output — just the exit code—Compare two MCP server versions. Use this in CI to catch quality regressions before they reach production — fails if grade dropped, score regressed, or token footprint grew too much.
mcpx diff \
--base https://staging.your-server.com/mcp \
--head https://prod.your-server.com/mcp
# With custom thresholds
mcpx diff \
--base https://staging.your-server.com/mcp \
--head https://prod.your-server.com/mcp \
--score-drop 5 \
--token-threshold 10
# JSON output
mcpx diff \
--base https://staging.your-server.com/mcp \
--head https://prod.your-server.com/mcp \
--format json--base <url>Base server URL (required)—--head <url>Head server URL to compare against (required)—--score-drop <n>Fail if score drops more than N points10--token-threshold <n>Fail if token footprint increases more than N%20--format jsonOutput raw JSON—Connect to a server and list all tools, resources, and prompts it exposes — with descriptions.
mcpx inspect https://your-server.com/mcp
# JSON — includes full inputSchema for each tool
mcpx inspect https://your-server.com/mcp --format json--format jsonFull JSON output including tool schemas—Ping a server and return its status and latency. Exits 0 if up, 1 if down, 2 if unreachable.
mcpx health https://your-server.com/mcp
# JSON output
mcpx health https://your-server.com/mcp --format json--format jsonOutput JSON with status, latencyMs, url—0Passed — grade meets threshold, no blocking issues1Failed — errors found, grade below min-grade, or token budget exceeded2Unreachable — server could not be contacted, timed out, or requires authAdd a quality gate to any workflow in one step:
Minimal — fail CI on errors
- name: Lint MCP server
run: npx @samsec/mcpx lint ${{ secrets.MCP_SERVER_URL }}Full workflow with grade + token gates
# .github/workflows/mcp-lint.yml
name: MCP Schema Quality
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint MCP server
run: |
npx @samsec/mcpx lint ${{ secrets.MCP_SERVER_URL }} \
--min-grade B \
--token-budget 5000Diff — catch regressions on PRs
- name: Diff MCP schema
run: |
npx @samsec/mcpx diff \
--base ${{ secrets.MCP_STAGING_URL }} \
--head ${{ secrets.MCP_PROD_URL }} \
--score-drop 5 \
--token-threshold 10Add MCP_SERVER_URL in your repository's Settings → Secrets and variables → Actions.
Deductions per issue
−15 pts−5 pts−1 ptGrade thresholds
A90–100B75–89C60–74D40–59F0–39A server with zero tools, resources, and prompts automatically receives grade F. Full grading methodology →