MCP Config & Schema Validator

What the MCP validator finds

The validator does two jobs. Under Client config it reads an AI client's MCP config the way the client does and lists what would stop a server from loading: servers under a key the client never reads, a command line packed into the command field, a value of the wrong type, a placeholder in another client's syntax, a token written out in full. Under Tool schemas it checks the tools an MCP server lists against the specification: the fields a tool needs, its inputSchema and outputSchema as JSON Schema, the naming rules and the x-mcp-header annotation. Each problem points at its line and column, and for the common mistakes the output shows your input with the fix applied.

It knows the configs of Claude Desktop, Claude Code, Cursor, VS Code, Devin (formerly Windsurf) and OpenAI Codex, including JSON with comments and Codex's TOML, and the tool definitions of MCP revisions 2026-07-28 and 2025-11-25.

How to check an MCP config or tool schemas

Examples

{
  "servers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"] }
  }
}

Line 2, column 3: Claude Desktop reads servers from mcpServers, not servers. Rename servers to mcpServers: servers is VS Code's key. (MCP_WRONG_TOP_LEVEL_KEY)

{
  "mcpServers": {
    "git": { "command": "uvx mcp-server-git --repository /Users/me/code/app" }
  }
}

Line 3, column 25: The command includes its arguments. Put uvx in command and each argument in args; the client runs the command as one program name. (MCP_COMMAND_HAS_ARGS)

{
  "name": "get_weather",
  "description": "Get the current weather for a city.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": { "type": "strng" }
    },
    "required": ["city", "units"]
  }
}

Line 7, column 25: In the inputSchema of get_weather, properties.city.type is "strng", which isn't a JSON Schema type. The types are string, number, integer, boolean, object, array and null; a list of them takes any of those. (MCP_JSON_SCHEMA_INVALID)
Line 9, column 26: In the inputSchema of get_weather, required names "units", which properties leaves out. Add it to properties with its type and description, or remove it from required: a model can't fill in a parameter it doesn't see. (MCP_REQUIRED_NOT_IN_PROPERTIES)

Why a client skips a server

Most configs that fail to load have one of a few mistakes:

• The servers are under the wrong key. VS Code reads servers; the other JSON clients read mcpServers; Codex wants [mcp_servers.<name>] tables. Snippets copied from a README sometimes have no key at all, and VS Code's older settings.json kept them inside mcp.
• The command holds its arguments. A client starts the command as one program, so "npx -y package" looks for a program with spaces in its name. The program goes in command, everything after it in args.
• npx waits for an answer. Without -y, npx asks before it downloads a package, and nobody is there to reply.
• A value has the wrong type. Arguments and environment values are strings: 8080 without quotes is a number. VS Code alone takes numbers in env.
• The client reads the entry differently. Claude Code treats a server without type as local, so a url alone isn't enough there, and VS Code needs type on every server.

Which client a config is for

Codex's TOML and VS Code's servers key give their client away. Claude Desktop, Claude Code, Cursor and Devin all use mcpServers, so the validator looks for what only one of them documents: envFile or ${env:NAME} for Cursor, ${NAME} or headersHelper for Claude Code, transport or disabled for Devin. A config with plain local servers fits all four, and the validator then checks only what they share and says so. Choose the client under Client to check everything, including the fields, placeholders and comments that client reads.

Fields each client documents

A field outside this list is not always an error, since clients add settings over time, but a misspelt one is silently ignored: enviroment instead of env leaves the server without its variables. The validator lists such fields as warnings. Comments are fine in VS Code's mcp.json; Claude Desktop's and Claude Code's documentation shows only plain JSON, and Cursor's and Devin's shows comments in examples without describing them.

Placeholders and secrets

A placeholder works only in the syntax its client replaces; in any other, the server receives the text itself. Claude Code reads ${NAME} and ${NAME:-default}, Cursor and VS Code read ${env:NAME}, and VS Code also reads ${input:id} once the id is defined under inputs. Codex reads variables through env_vars, bearer_token_env_var and env_http_headers. Claude Desktop replaces nothing, and Devin only in its OAuth fields.

Values that look like keys or tokens, found by their name or by a known key format, are listed with the way the client keeps them out of the file. The config never leaves your browser.

What a tool definition needs

A tool is an object with a name and an inputSchema; title, description, outputSchema, annotations and icons are optional. Clients call the tool by its name, and the specification asks for 1 to 128 letters, digits, _, - and ., unique within the server: get_weather or admin.tools.list, not get weather. The model reads the description to decide when to call the tool, so the validator flags one that is missing or only a word or two. A tool written for a model API, with input_schema or parameters, needs its schema renamed to inputSchema.

Tool schemas and JSON Schema

Tool arguments are always one JSON object, so an inputSchema needs "type": "object" at its top, even for a tool without parameters: { "type": "object", "additionalProperties": false } takes only an empty object. Schemas are JSON Schema 2020-12 unless their $schema names another dialect. The validator checks 2020-12 and draft-07 schemas against their official meta-schemas, so a misspelt type, a required that isn't a list or a pattern that isn't a valid regular expression shows up at its place. It also flags a name in required that properties leaves out, since the model never sees what to put there.

Header parameters with x-mcp-header

Since 2026-07-28, a parameter's schema can carry x-mcp-header to send its value as an HTTP header, Mcp-Param-{name}, on Streamable HTTP, so a gateway can route a call without reading its body. A client must leave out a tool whose annotation breaks the rules: the name is an HTTP token without spaces, different from the tool's other header names ignoring case, on a string, integer or boolean parameter reached from the top through properties alone, not inside items, anyOf or $defs. Header values travel in the open, so keep keys, tokens and personal data out of them.

Which MCP revision to choose

Choose the revision your server's SDK implements. 2026-07-28 made every tools/list result carry resultType, ttlMs and cacheScope, added x-mcp-header, moved tasks and the tools' execution field into an extension, and let an outputSchema be any JSON Schema. Under 2025-11-25 an outputSchema is an object schema with "type": "object", like an inputSchema, and each schema under properties is an object rather than true or false.

Suggested fixes

A few mistakes have a fix the validator can make without guessing. In a config, a wrong root key is renamed, servers written at the top are put inside the client's key, and a command line is split into command and args, with -y added for npx. In tool schemas, an inputSchema without a type gets "type": "object", and so does an outputSchema under 2025-11-25. The output shows the whole input with these changes, in its own indentation and with its comments; your input stays as it is. Other problems need a decision, such as which value a secret should come from, so they are listed with a hint instead. Codex's TOML gets hints only.

Options

Common errors and fixes