Skip to main content
Glama

mcp-doctor

ci

Live playground: https://mcp-doctor.kfairley9999.workers.dev

MCP configs fail quietly. A missing -y, a url where the client reads serverUrl, or an npx that a GUI cannot see on PATH looks like a client bug and is usually the config. mcp-doctor checks the file against the client that will load it, rewrites it for the client you actually use, and opens a real initialize handshake so you can see the failure.

Three surfaces, one library:

  • mcp-doctor CLI: validate, lint, convert, doctor

  • an MCP server, so an agent can inspect the setup it is running inside

  • a Cloudflare Workers playground that checks a paste in the request and then drops it

The problem

There is still no standard MCP config schema. modelcontextprotocol/modelcontextprotocol#292 (51 thumbs-up) asks for one. Until it exists, every client invented a dialect:

  • Claude Desktop: claude_desktop_config.json

  • Claude Code: .mcp.json

  • Cursor: .cursor/mcp.json

  • VS Code: .vscode/mcp.json

  • Windsurf: mcp_config.json

  • Cline: cline_mcp_settings.json

  • Codex: ~/.codex/config.toml

  • Gemini CLI: ~/.gemini/settings.json

  • Zed: context_servers inside settings.json

The practical failures are well known. modelcontextprotocol/servers#64 (147 thumbs-up) is npx disappearing under nvm because GUI apps do not load the shell. cline/cline#902 is npx on Windows, which is a .cmd shim CreateProcess will not run. anthropics/claude-code#5826 is Claude Code refusing a custom server that was pasted from another client's example.

SchemaStore does not ship a schema for these filenames. Converters such as mcp-config-converter, mcp-config-sync, and mcp-installer copy or install a block. None of them validate it, lint it, or speak MCP to the server.

Related MCP server: MCP Doctor

Client support

"Yes" means the field survives a conversion into that client. A blank cell is reported as a drop, with the reason, instead of being invented.

Field

Claude Desktop

Claude Code

Cursor

VS Code

Windsurf

Cline

Codex

Gemini CLI

Zed

Root key

mcpServers

mcpServers

mcpServers

servers

mcpServers

mcpServers

mcp_servers

mcpServers

context_servers

Format

JSON

JSON

JSONC

JSONC

JSON

JSON

TOML

JSON

JSONC

command, args, env

yes

yes

yes

yes

yes

yes

yes

yes

yes

cwd

yes

yes

yes

envFile

yes

yes

Remote URL

url + type

url

url + type

serverUrl

url + type

url

httpUrl / url

url

headers

yes

yes

yes

yes

yes

http_headers

yes

yes

Timeout

ms

ms

seconds

ms

Disabled

disabled

enabled

autoApprove

yes

trust

yes

SSE kept distinct

yes

yes

yes

yes (url)

WebSocket

yes

Interpolation

none

${VAR}

${env:VAR}

${env:VAR}, ${input:id}

${env:VAR}, ${file:}

none

none

$VAR, ${VAR}

none documented

Sources for the golden fixtures: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex, Gemini CLI, Zed.

Cursor, Windsurf, and Zed store HTTP and SSE as the same URL. Conversion keeps the URL and says the transport label will not survive. Codex's url is streamable HTTP. Claude Desktop's JSON file only launches stdio. A remote server is omitted and reported. This tool does not wrap it in mcp-remote for you.

Lint rules

Each rule has a fix sentence. mcp-doctor lint --fix applies only the two edits that cannot change which program you meant: prepend -y, and split a command string into command plus args.

Rule

What it catches

Fix

npx-missing-yes

npx or npm exec with no -y / --yes

Put -y first. A prompt never gets a keypress.

windows-cmd-wrapper

npx, npm, pnpm, yarn launched directly

command: "cmd", args: ["/c", "npx", ...]. Error on Windows, warning elsewhere. cline#902.

command-not-on-path

stdio command missing from PATH

Absolute path, or install it. Needs a local probe.

version-manager-shadow

node/npx resolves outside nvm, Volta, fnm, or asdf

Point command at that manager's shim. servers#64.

missing-env-reference

${VAR} / ${env:VAR} / $VAR unset, or an empty secret

Export it where the client can see it. GUI apps skip the shell rc.

env-interpolation-syntax

${VAR} where the client wants ${env:VAR}, or the reverse

Rewrite to the form that client expands.

plaintext-secret

Tokens, keys, URL passwords, placeholders

Use the client's interpolation. The message does not echo the value.

url-field-name

url vs serverUrl vs httpUrl

Rename to the field that client reads.

transport-mismatch

type disagrees with command/url, or Claude Code has a URL and no type

Set the type the client documents. Cline with no type means SSE.

stdio-missing-command

stdio entry with no command

Set command.

remote-missing-url

http/sse/ws entry with no URL

Set the URL field.

command-contains-args

command is "npx -y pkg"

Split it. Clients do not run a shell.

relative-path

./, ../, or ~

Absolute path. ~ is not expanded.

insecure-http

http:// to a non-loopback host

Use https. Credentials on cleartext are an error.

suspicious-timeout

30 where the unit is milliseconds, or 30000 where Codex wants seconds

Match the unit.

lint prints text, --format json, or --format sarif. Warnings exit 0 unless --strict. Errors exit 1.

Install

npm ci
npm run build

The CLI is node packages/cli/dist/main.js, also npm run mcp-doctor -- <args> from the repo root. This package is not published to npm, and the npm name mcp-doctor belongs to an unrelated package, so npm install mcp-doctor does not install this tool.

npm run mcp-doctor -- validate .cursor/mcp.json --client cursor
npm run mcp-doctor -- lint .mcp.json --format sarif
npm run mcp-doctor -- convert claude_desktop_config.json --from claude-desktop --to windsurf
npm run mcp-doctor -- doctor --timeout 10000

doctor discovers the config files listed above, lints them, and performs an MCP initialize handshake (stdio, streamable HTTP, and a best-effort SSE connect) with a timeout. It only reads config files. It does start the servers those files name. Pass --home and --root to look somewhere other than your real home, and --no-handshake to skip the spawn.

A file of - reads stdin. convert writes the config to stdout and the carry report to stderr, so the config can be piped.

MCP server

The server speaks stdio through @modelcontextprotocol/sdk and exposes validate_config, lint_config, convert_config, diagnose_server, and list_client_configs. diagnose_server is the handshake. list_client_configs does not start servers.

Build first (npm run build), then point the client at packages/mcp-server/dist/main.js. Use the absolute path on your machine.

Claude Desktop, claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doctor/packages/mcp-server/dist/main.js"]
    }
  }
}

Cursor, .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doctor/packages/mcp-server/dist/main.js"]
    }
  }
}

Claude Code, .mcp.json:

{
  "mcpServers": {
    "mcp-doctor": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-doctor/packages/mcp-server/dist/main.js"]
    }
  }
}

Architecture

flowchart LR
  subgraph surfaces
    CLI["CLI validate lint convert doctor"]
    MCP["MCP server stdio"]
    WEB["Workers playground"]
  end
  CORE["@mcp-doctor/core"]
  NODE["core/node discover and handshake"]
  CLI --> CORE
  CLI --> NODE
  MCP --> CORE
  MCP --> NODE
  WEB --> CORE
  CORE --> SCHEMAS["JSON Schemas per client"]
  CORE --> LINT["15 lint rules"]
  CORE --> CONV["parse and emit"]
  NODE --> CORE

The playground imports only the pure library. Handshake and PATH checks need a process, and running them on Cloudflare would execute whatever command was pasted. They stay on the machine.

Playground

Paste a config, see validation, lint, and the same servers emitted for every client. The page posts the text (up to 64KB) to /api/analyze on this Worker. The Worker answers and discards the body. It does not log the body, store it, or send it anywhere else.

Live demo: https://mcp-doctor.kfairley9999.workers.dev (Cloudflare Workers free tier).

Terminal demo of lint, convert, and doctor

Deploy

The live demo runs on the Cloudflare Workers free tier. CI runs the dry run and does not deploy. Nothing in the Worker uses a paid binding. No secrets, no KV, no D1.

cd playground
npx wrangler login
npx wrangler deploy

npm run playground:dry-run from the repo root bundles the Worker and stops before upload. Local preview:

npx tsc -b packages/core
npm run dev -w mcp-doctor-playground

That listens on port 47471.

Development

npm ci
npm test
npm run test:coverage
npm run lint
npm run schemas:validate

CI on Node 20 and 22 runs lint, typecheck, tests with the 85% coverage gate, and schema self-validation. The playground bundle and wrangler deploy --dry-run run on Node 22 only, because Wrangler 4 requires Node 22.12 or newer.

Limitations

  • The schemas follow public docs as of November 2026. Clients change fields without a spec. A passing schema means the shape is one they document, not that this week's build still accepts it.

  • Same-client emit is stable in the canonical model, not byte-for-byte. Codex comments and key order are not preserved. Zed's legacy { command: { path } } object is read and written back in the flat form.

  • ~/.claude.json holds project-scoped servers under projects. doctor reads those. convert rewrites the top-level mcpServers map.

  • doctor and diagnose_server run the configured command. They are not a sandbox. Review the file first.

  • A green PATH check in the terminal can still fail inside Claude Desktop or Cursor, because those processes do not source your shell. The version-manager rule exists for that case and can still miss a manager it cannot see without launching a shell.

  • WebSocket handshake is not implemented. SSE is a short read for the endpoint event, then one POST.

  • Nested interpolation such as ${A:-${B}} is not modeled. Claude Code's credential names that expand to empty are not special-cased.

  • The playground cannot check PATH, nvm, or a live server. Doing so would run untrusted commands and contact arbitrary URLs.

  • Not published to npm. Not submitted to SchemaStore.

Roadmap

  • Submit the schemas to SchemaStore once a client freezes a shape.

  • Fixes for the mechanical renames (url to serverUrl, ${env:VAR} to ${VAR}) behind an explicit flag.

  • A file watcher for lint.

  • Continue, Roo, and other clients that copy one of these dialects.

  • A fuller SSE and WebSocket handshake.

How it was built

Designed and directed by Kevin Fairley, built with AI coding agents.

MIT license. See CONTRIBUTING.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides health checks, binary validation, and auto-repair for MCP configurations in Claude Desktop, Cursor, and Cline.
      3
      15 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP client to detect Claude Code configuration that is silently ignored, such as agent files that fail to load, unknown frontmatter fields, parent-folder settings, conflicting MCP server entries and drift since a baseline. Exposes read-only tools that return findings with exact edits, the fix prompt, and explanations of each check, without modifying any files.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to inspect and diagnose their own MCP setup by exposing read-only tools that audit configured servers, report which coding agents have configs, surface misplaced or duplicated registrations, and list curated preset packs. It also powers CLI workflows for checking handshake, tool lint, and tool-surface quality scores of any stdio server.
      32 npm
      MIT