How to Validate Your MCP Config

Common Configuration Errors

Most MCP connection failures come down to configuration mistakes rather than server bugs. The three most frequent errors are malformed JSON, missing required fields, and incorrect paths to server binaries.

A missing comma or trailing comma in your JSON config will silently prevent the client from loading any servers. Missing the command field means the client has no idea what binary to launch. And a typo in the path to npx or a server package will produce a cryptic "spawn" error that sends developers down the wrong debugging path.

Before you start inspecting transport logs or reinstalling packages, always validate your configuration file first.

Validating Claude Desktop Config

Claude Desktop reads its MCP configuration from claude_desktop_config.json. Here is a valid configuration that connects to the filesystem MCP server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Key things to check:

• Top-level key must be mcpServers (not servers or mcp).
• Each server entry needs at minimum a command field.
• The args array must contain strings, not numbers or objects.
• The env object is optional but must be a flat key-value map of strings if present.

Run your config through a JSON linter before anything else. Most editors have built-in JSON validation, or you can use jq from the command line:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

If jq returns an error, your JSON syntax is broken.

Environment Variables

MCP servers frequently rely on environment variables for API keys, database URLs, and other secrets. A common mistake is defining these variables in your shell profile but not in the MCP config's env block.

When a client like Claude Desktop spawns an MCP server, it does not inherit your shell environment by default. You must explicitly pass required variables through the env field in your config, or use a wrapper script that sources your profile before launching the server.

To debug environment issues, add a simple echo server to your config that prints its environment:

env | grep -i "api_key\|database_url\|token"

If the variables you expect are missing, add them to the env block in your configuration.

Using the Config Validator

Rather than manually checking each field, you can use CodexSpot's MCP Config Validator. Paste your configuration JSON into the validator and it will check for:

• Valid JSON syntax
• Required fields (command at minimum)
• Known server package names and common typos
• Environment variable placeholders that were never replaced

The validator provides instant, actionable feedback so you can fix issues before restarting your client. Combined with the troubleshooting tips above, you should be able to resolve most connection failures in under a minute.