MCP Server Validator

This page is the canonical guide to linting MCP client JSON with DevUtilities’ MCP Validator. Paste your mcpServers config above while you read, or jump to a topic below. Parsing stays in your browser — commands, paths, and env values are never uploaded.

MCP Validator is a client-side linter for Cursor and Claude Desktop mcpServers JSON. It walks each server entry, checks stdio vs HTTP/HTTPS transport rules, validates args and env shapes, and reports issues with JSON-pointer paths so you can fix configs before paste.

What you get

• Blocking errors vs non-blocking warnings with path pointers (mcpServers.serverName…)
• Stdio checks: command required; args array of strings (warn if missing)
• Remote checks: url must be http or https; malformed URLs fail
• Env object values must be strings — numeric ports must be quoted
• Unknown keys and dual command+url transports flagged as warnings
• ok status only when zero errors remain (warnings alone do not fail)

Use this tool when

• You are editing Cursor mcp.json or Claude Desktop MCP settings
• You want lint before committing a shared team MCP template
• You need a readable report for CI docs or PR review
• You are swapping stdio filesystem servers for remote HTTP MCP endpoints

Prefer a related tool when

• You need schemas + MCP + prompts in one session → AI Agent Builder
• You only need JSON Schema from an example payload → Structured Output Generator
• You need token budgets for the assembled agent → LLM Token Counter or Agent Builder

The report panel separates severity so you can unblock paste first, then clean warnings.

Treat warnings as production debt: dual transports and unknown keys often mean the client will ignore half your config or reject it later.

First-time walkthrough for a Cursor or Claude Desktop config.

1. Copy the JSON that contains a top-level mcpServers object from your client config file.
2. Paste it into the validator input panel (replace sample content).
3. Scan errors first — fix missing command/url, malformed URLs, and type mismatches.
4. Resolve warnings: add args for stdio servers, remove dual transports, drop unknown keys.
5. Confirm env values are quoted strings ("3000" not 3000).
6. Re-check until ok is true and only intentional warnings remain.
7. Paste the corrected JSON back into Cursor or Claude Desktop.
8. Optionally copy the issue list into a PR or CI checklist for the team.

Problem: a teammate’s Cursor mcp.json fails silently after adding a filesystem MCP server with a wrong path or missing args.

How this tool helps

1. Paste the project or global mcp.json envelope into the validator.
2. Fix the stdio entry: command (e.g. npx), args with the package and absolute path.
3. Confirm env placeholders are strings; keep real secrets out of the paste.
4. Copy the cleaned JSON back into Cursor and reload MCP servers.

Outcome: Cursor loads the server on first try with a shared, linted template.

Problem: Claude Desktop rejects a remote MCP URL because the scheme is wrong or command and url were both set.

How this tool helps

1. Paste the Claude Desktop MCP JSON fragment.
2. For remote servers, keep only url with http:// or https://.
3. Remove command/args from that entry (or remove url if you meant stdio).
4. Re-validate, then paste into Claude Desktop settings.

Outcome: a single clear transport per server that matches Claude’s client expectations.

Problem: teams commit broken mcpServers snippets into docs or starter repos and discover failures only on a developer’s machine.

How this tool helps

1. Lint the canonical mcpServers JSON in the browser before merge.
2. Copy the error/warning report (paths + messages) into the PR description.
3. Require ok = true (zero errors) as a human checklist item for MCP-related PRs.
4. Keep production secrets as placeholders in the committed template.

Outcome: MCP templates stay mergeable and onboarding stops failing on day one.

Problem: API keys in env blocks get pasted into chat, screenshots, or shared validators during debugging.

How this tool helps

1. Replace real secrets with placeholders (e.g. YOUR_API_KEY) before pasting.
2. Lint structure only — the validator never needs live credentials.
3. Inject real values only in the local desktop client or secret store.
4. Rotate any key that was pasted into a shared channel.

Outcome: you still catch type and transport bugs without exfiltrating production secrets.

Each server entry must define exactly one transport style. Mixing both is a warning; defining neither is an error.

Optional known keys include env, headers, and disabled. Unknown keys produce warnings so you can verify against your client’s schema.

Client configs serialize process environment as JSON. Non-string values are a common copy-paste bug from TypeScript objects or YAML.

• Valid: { "env": { "API_KEY": "sk-test", "PORT": "3000" } }
• Invalid: { "env": { "PORT": 3000 } } — PORT must be a string
• env itself must be a plain object, not an array
• Lint with placeholders; never require production secrets to validate shape

Error: each server requires either a command (stdio) or a url (SSE/HTTP).

Why it happens

Empty objects, incomplete copy-pastes, or renaming keys leave a server with neither transport field.

Diagnose

Find the issue path mcpServers.<name>. If both command and url are absent, that entry cannot start.

Fixes

1. For local servers: set command to the executable (e.g. npx) and args to the package + path list.
2. For remote servers: set url to a full http:// or https:// endpoint and remove command/args.
3. Re-paste and confirm the error disappears before addressing warnings.

Error: environment variable values must be strings.

Why it happens

JSON numbers, booleans, or nested objects were pasted into env from another config format.

Diagnose

Open the reported path mcpServers.<name>.env.<KEY>. The value type is not a string.

Fixes

1. Quote numeric ports and flags: "3000", "true".
2. Flatten nested objects into string values or move them out of env.
3. Re-validate until env-related errors are gone.

Warnings about unknown keys are separate — fix type errors first.

Error: missing top-level "mcpServers" object.

Why it happens

Cursor and Claude Desktop expect the root key mcpServers. Wrappers like servers, mcp, or a bare server map do not match.

Diagnose

If the root parses but mcpServers is undefined, you pasted the wrong envelope or only an inner server object.

Fixes

1. Wrap your servers: { "mcpServers": { "my-server": { ... } } }.
2. Do not rename mcpServers to match other product docs.
3. Ensure the root is a JSON object, not an array.

• Lint before paste into Cursor or Claude Desktop — catch transport bugs offline
• One transport per server: command or url, never both
• Always include args for stdio CLI servers (use [] if empty)
• Keep env values as strings; quote numbers
• Use placeholders for secrets in shared docs and this browser tool
• Prefer absolute, least-privilege paths for filesystem MCP servers
• Re-lint after every path, package, or URL change
• Use AI Agent Builder when you also need schemas, prompts, and token budgets