mcp-toolguard

mcp-toolguard is a tool designed to monitor contracts, detect drift, and perform security checks for MCP servers in both continuous integration (CI) environments and production. It addresses the problem of silent breaking changes in MCP server contracts that can disrupt agent operations without triggering build failures or type-checking errors. By capturing a canonical snapshot of a server's tools, schemas, and capabilities, mcp-toolguard enables versioned contract management directly within a repository, using a deterministic hash to ensure consistency.

The tool employs a single engine that operates across three layers: contract validation, drift detection, and security analysis. json file, which is committed and versioned with the codebase. Drift detection classifies every change as breaking, compatible, or suspicious, using semantic diffing rather than simple text comparison. This process highlights removals and type changes as breaking, additions as compatible, and changes to descriptive text as suspicious, identifying potential prompt-injection surfaces. Security checks are enforced through 15 rules targeting threats such as tool poisoning, credential-shaped parameters, cross-tool coercion, and hidden characters, with each finding accompanied by supporting evidence.

mcp-toolguard integrates with CI pipelines through a GitHub Action and can be run via the command line interface. It supports scheduled checks and alerts in production, including notifications through Slack or webhooks. The tool validates server contracts against both the current and upcoming MCP specification versions, providing independent reports for each to anticipate future breaking changes. The baseline is the accepted state, and only new findings block CI or trigger production alerts.

The platform offers a free tier that operates entirely offline, requiring no signup and minimal setup. mcp-toolguard is open source and distributed under the MIT license, with installation available via pip. It is suitable for teams managing MCP servers who need to ensure contract stability, detect unauthorized changes, and enforce security policies throughout the software lifecycle.