akshay-th

MCP Preflight — Development skill for Claude Code

Development community

Check every MCP server config (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI, Codex, OpenCode) for broken JSON, GUI PATH issues, stdout pollution, leaked secrets and failing hands.

How to install MCP Preflight

This entry records only its repository, not the path inside it, so there is no exact command to give. Open akshay-th/mcp-preflight and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What MCP Preflight does

Alternatives in Development

Agentic Stack — One brain, many harnesses 2.2k ★
Chops — 1,000+ macOS app to browse, edit, and manage skills across Claude Code, Cursor, Codex, Windsurf, and Amp 1.1k ★
Claudecode — Open Source ClaudeCode Leaked 1k ★

README

mcp-preflight

**One command that checks every MCP server config on your machine and tells you why a server won't start, before your agent fails without saying why.**

MCP servers fail in a handful of recurring ways, and each client reports them differently or not at all:

Symptom	Real cause	What mcp-preflight reports
All servers vanished from Cursor or Claude Desktop	One trailing comma in the config file	`invalid-config` with line and column
`spawn npx ENOENT` in Claude Desktop, but it works in your terminal	Node comes from nvm or Homebrew, and GUI apps get `/usr/bin:/bin:/usr/sbin:/sbin`	`gui-path`, with the absolute path to use instead
Server "connected" but no tools, or random JSON errors	The server prints logs to stdout, the protocol channel	`stdout-pollution` (with `--live`)
Server exits immediately	Missing token or bad argument	`live-exit`, plus the last lines of its stderr
Works today, breaks after `nvm use 22`	Command points into a version manager directory	`version-manager`
`npx` fails on Windows	`npx` is a `.cmd` shim, and spawning without a shell fails	`windows-cmd-shim`, suggesting the `cmd /c` fix
Agent feels slow and dumb	One server adds 30k tokens of tool definitions to every request	`context-heavy`, from a token estimate per server
Token committed to git	API key pasted into `env`	`plaintext-secret` (masked), and `readable-secrets` if the file mode is 644

Some tools check one client's schema in a browser, and some do live checks for a few clients. `mcp-preflight` covers **all eight major clients, including Codex's TOML and Gemini CLI**. It runs locally with zero dependencies and gives a CI-friendly exit code.

Usage

npx -y github:akshay-th/mcp-preflight            # static checks, all clients
npx -y github:akshay-th/mcp-preflight --live     # also start each server and run initialize + tools/list
npx -y github:akshay-th/mcp-preflight --live --si