M MCP Tool Validator

MCP governance for agent tool surfaces

Validate tool definitions before agents rely on them.

Separate MCP specification compliance from governance policy and heuristic advice. Validate files or live servers with 57 rules, provenance-aware findings, and reproducible run metadata.

View Source Browse Rules
57 validation rules
5 rule categories
3 report formats
1,086 tests in the current suite
Google Drive MCP · compliance profile 
$ mcp-validate --server https://drivemcp.googleapis.com/mcp/v1 \
    --discovery-spec-version 2025-11-25 --spec-version 2026-07-28 \
    --profile compliance
MCP Tool Validator v0.2.0

Validating: 8 tool(s)
Profile: compliance
Validation spec: 2026-07-28
Discovery spec: 2025-11-25
…per-tool findings omitted…
Summary: 8/8 tools valid
  Errors: 0  Warnings: 48  Suggestions: 17

Maturity: MATURE (86/100)
MCP specification compliance passed.
Governance threshold passed.
# excerpt of a run on 2026-10-02

Three Signals, Clearly Separated

A strict project recommendation is not automatically an MCP violation. Every result carries its authority and the report keeps protocol compliance distinct from the active policy threshold.

S

Specification

Finalized MCP requirements such as tool shape, JSON Schema, metadata, and x-mcp-header.

G

Governance

Configurable defensive policy such as bounded inputs, annotations, pagination, and output controls.

H

Heuristics

Name- and text-based signals for model comprehension that benefit from human review.

Rule Coverage

The validator treats MCP tool quality as a cross-functional problem: protocol shape, security boundaries, naming, model comprehension, and runtime behavior hints all matter.

SCH

Schema

Required fields, JSON Schema validity, object-shaped inputs, and explicit required arrays.

NAM

Naming

MCP name grammar, uniqueness, consistent parameter casing, descriptive verbs, and tool-set grouping.

SEC

Security

Bounded inputs, URL and path constraints, sensitive defaults, safe headers, and context-aware heuristics.

LLM

LLM Fit

Actionable descriptions, parameter guidance, workflow cues, and ambiguity checks.

BP

Practice

Annotations, output schemas, parameter count, nesting depth, and usability guidance.

Use It Three Ways

Run it locally as a CLI, embed it in TypeScript, or start a small HTTP service. File and live-server inputs use the same rule engine.

1

CLI Gate

Validate JSON or YAML files and fail CI with --ci when effective-profile errors are present.

2

Library API

Call validate, validateFile, or validateServer from a release workflow.

3

HTTP Service

Run mcp-validate serve and post definitions plus validated configuration to /validate.

Proven Against a Live MCP Server

Runs against Google's managed Drive MCP server used legacy discovery and 2026-07-28 rule validation independently. All eight public tools passed the compliance profile (86/100 on the 2026-10-02 re-run, with its full report committed) without accessing Drive data or executing a tool.

Read the Google Drive Case Study

Documentation Map

The maintained documentation separates product behavior, rule semantics, architecture, verification, and real-server evidence.

Quick Commands

git clone https://github.com/chief-builder/mcp_tool_description_validator.git
cd mcp_tool_description_validator
npm ci && npm run build && npm link
mcp-validate examples/polished-tools.json --profile compliance
mcp-validate examples/needs-work-tools.json --verbose
mcp-validate --server "node ./server.js" --discovery-spec-version 2025-11-25
mcp-validate serve --port 8080