MCP Schema Validator

What Is MCP Schema Validation?

MCP schema validation is the process of checking that your MCP server definitions — tools, resources, and prompts — conform to the official Model Context Protocol specification. Every MCP server exposes its capabilities through structured JSON objects that clients like Claude Desktop, Cursor, and VS Code parse to understand what the server can do.

When these JSON definitions contain errors — missing required fields, invalid data types, malformed URIs, or incorrect naming conventions — the results range from silent failures (the client ignores your tools) to runtime errors that break the user experience. Validation catches these issues before deployment.

Our MCP Schema Validator goes beyond basic JSON syntax checking. It validates against the full MCP specification, checks for security vulnerabilities, evaluates best practices that improve AI model compatibility, and provides actionable fix suggestions for every issue found.

Understanding MCP Tool Definitions

Tool definitions are the most common MCP schema type. Every tool exposed by an MCP server must have three required fields: a name (a unique identifier following the pattern [a-zA-Z_][a-zA-Z0-9_-]*), a description (a human-readable explanation that AI models use to decide when to invoke the tool), and an inputSchema (a JSON Schema object defining the tool's parameters).

The inputSchema must be of type "object" and should define properties with individual type definitions and descriptions. A required array lists parameter names that must be provided. Each property should include a type (string, number, boolean, array, object) and ideally a description that helps the AI model generate correct values.

Well-written tool definitions are critical for reliable AI-tool interaction. The description quality directly affects how accurately AI models invoke your tools. Our validator checks not just specification compliance but also description quality and parameter documentation completeness.

MCP Resource and Prompt Schemas

Beyond tools, MCP servers can expose resources and prompts. Resources provide read access to data through URI-based addressing — think of them as data endpoints that AI clients can browse and read. Each resource requires a uri, a name, and optionally a description and mimeType.

Prompts are templated interaction patterns that guide how users and AI models interact with your server. They define reusable conversation starters with optional arguments. Each prompt requires a name and can include an arguments array defining the parameters the prompt accepts.

The validator supports all three schema types and can auto-detect which type your JSON represents. For full server manifests that combine tools, resources, and prompts, each element is validated individually while also checking the overall manifest structure.

Common MCP Validation Errors

After validating thousands of MCP definitions, here are the most common errors we see:

• Missing description on tools — The spec requires tool descriptions, and AI models heavily rely on them. Without descriptions, models cannot determine when to use your tool.
• Invalid tool names — Tool names must start with a letter or underscore and contain only alphanumeric characters, underscores, and hyphens. Spaces, special characters, and names starting with numbers are invalid.
• Wrong inputSchema.type — The input schema type must be "object". Using "string" or other types at the top level violates the specification.
• Missing property types — Every property in the input schema should specify a type. Without types, clients cannot validate or transform inputs correctly.
• Invalid resource URIs — Resource URIs must follow the URI specification. Common mistakes include missing the scheme (protocol) prefix or using invalid characters.
• Empty required arrays referencing non-existent properties — If your required array references property names that do not exist in properties, clients may behave unpredictably.

MCP Security Best Practices

Security is a critical concern for MCP servers, which by design give AI models access to external systems. Research by security firms has found that a significant percentage of MCP implementations contain vulnerabilities like command injection, SSRF, and arbitrary file access.

Our security scanner checks for the most common vulnerability patterns:

• Command injection — Tool definitions that pass unvalidated user input to shell commands. The scanner checks for eval, exec, backtick execution, and pipe chaining patterns.
• Hardcoded credentials — API keys, tokens, and passwords embedded directly in tool definitions or manifests instead of being loaded from environment variables.
• Overly broad file access — Wildcard patterns like *, /**, or root-level paths that grant access to the entire file system instead of specific directories.
• Missing input validation — Tools with no input schema properties or required fields, allowing any data to be passed without validation.
• Unrestricted network access — Configurations that allow connections to any host instead of whitelisting specific endpoints.

Each security finding includes a severity rating (critical, warning, or info) and specific remediation guidance. For a more comprehensive security audit, see our upcoming MCP Security Scanner tool.

Validation Tips for Better AI Compatibility

Beyond specification compliance, the quality of your MCP definitions directly affects how well AI models interact with your tools. Here are best practices that our validator checks:

• Write detailed descriptions (20+ characters) — AI models use descriptions to decide when to use a tool. Vague descriptions like "Query data" are far less effective than "Search the PostgreSQL database for customer records matching a name, email, or account ID."
• Describe every parameter — Each property in your input schema should have a description. This helps AI models generate correct arguments without guessing.
• Use enum constraints when possible — If a parameter only accepts specific values, define them with enum. This eliminates invalid inputs and helps AI models present options.
• Keep tool counts reasonable — Servers with more than 50 tools can cause performance issues in some clients. Consider splitting large toolsets across multiple servers.
• Add version information to manifests — Version strings help with debugging, changelog tracking, and client compatibility management.