mcpgate

Automated quality gate for MCP servers — ruff + pytest for MCP.

The problem

When an MCP tool description is vague, the AI agent misuses the tool — even though the code behind it is perfect. This failure is invisible to unit tests because it happens at the AI-interpretation layer. Research documents the scale:

• An arXiv study of 103 major MCP servers (856 tools) found tool descriptions systematically "smelly and costly" (arXiv:2602.14878).
• An AWS-led study found 97.1% of MCP tool descriptions contain at least one quality defect.

mcpgate catches these defects before agents hit them in production. It speaks the real protocol, so it works with any server — FastMCP, the official Python SDK, or TypeScript servers — over stdio or HTTP.

Quickstart

uv tool install mcp-gatekeeper    # or: pip install mcp-gatekeeper

mcpgate lint "uvx mcp-server-fetch"
mcpgate doctor "uvx mcp-server-fetch"

Exit codes are CI-friendly: 0 clean, 1 findings (fail the build), 2 connection or protocol error.

Example output

    warning  MCP101  Tool `delete_record`: description too short (7 words; minimum 8)  src: tools/delete_record
    warning  MCP105  Tool `delete_record`: description does not state error/return behavior  src: tools/delete_record
    warning  MCP303  Tool `delete_record`: destructive operation without a confirmation parameter  src: tools/delete_record
    error    MCP301  Tool `run_command`: suggests command execution without a safety note  src: tools/run_command
    warning  MCP101  Tool `run_command`: description too short (7 words; minimum 8)  src: tools/run_command
    warning  MCP105  Tool `run_command`: description does not state error/return behavior  src: tools/run_command
    warning  MCP101  Tool `search`: description too short (2 words; minimum 8)  src: tools/search
    warning  MCP105  Tool `search`: description does not state error/return behavior  src: tools/search
    info     MCP204  Tool `search`: description repeats the tool name (wasted tokens)  src: tools/search
    ———
    found 9 problems (1 errors, 7 warnings)
    run `mcpgate lint --explain CODE` for details

Formats: --format text|json|sarif (SARIF plugs into GitHub code scanning). Filter with --select MCP3xx --ignore MCP401; inspect a rule with --explain MCP101; fail on warnings with --strict.

Rules (v0.1)

Pytest plugin

Install with the test extra, then contract-test your tools over the real protocol:

pip install "mcp-gatekeeper[test]"

import pytest
from my_server import mcp  # your FastMCP / MCP server object


@pytest.mark.parametrize("mcp_server", [mcp], indirect=True)
def test_search(mcp_server):
    result = mcp_server.call_tool("search", {"query": "hello"})
    assert result.is_error is False


@pytest.mark.parametrize("mcp_server", [mcp], indirect=True)
def test_contract(mcp_server):
    mcp_server.tool_contract("search")
    # asserts: described, valid object schema, described required params,
    # and the error path returns is_error instead of crashing

Or point a whole suite at one server: pytest --mcp-server "uvx mcp-server-fetch". Works in-memory for server objects (fully offline), stdio/HTTP for commands and URLs.

How it compares

Roadmap

• v0.2 — --fix: LLM-assisted rewriting of weak descriptions (the engine already carries the context needed per finding)
• Declarative YAML test suites and --baseline files
• Custom user rule plugins and a pre-commit hook package
• GitHub Action and official MCP servers registry integration

Contributing

See CONTRIBUTING.md. MIT licensed — see LICENSE.