Direct answer
An MCP entry being present in configuration does not prove the server started or negotiated the protocol. Verify each layer in order.
What this guide helps you solve
Fix MCP executable, arguments, environment, stdio, HTTP, protocol, authentication, and tool-discovery failures.
Confirm the symptom and blast radius
The client reports that an MCP server failed to start, initialize, authenticate, or expose tools.
The command may run manually but fail under the client because cwd, PATH, environment, stdout, or config scope differs.
- Capture the status or exception, response body, request ID, UTC time, client version, and final host before changing configuration.
- Compare one minimal request with the failing workflow to determine whether the issue is global, model-specific, or feature-specific.
- Keep credentials, full prompts, customer data, and private file contents out of screenshots and support bundles.
Common causes and ownership boundaries
Treat the error as evidence from one layer, not as proof that every downstream component failed. These are the highest-value causes to test first.
- The executable, arguments, working directory, PATH, or required environment variable is wrong.
- A stdio server writes logs or banners to stdout and corrupts protocol messages.
- An HTTP server is unreachable, unauthorized, or configured with the wrong URL or transport.
- Client and server fail initialize negotiation or tool schema discovery.
Run a layered minimal diagnosis
Start with a request that has the fewest moving parts. Preserve the same account, API host, and target model while removing optional features.
Change one variable at a time and retain the raw status, headers, response body, and timing. This separates client serialization from gateway and upstream behavior.
- 01Establish the boundaryConfirm server name, config scope, command or URL, arguments, cwd, and environment names.
- 02Create a baselineStart stdio directly with sanitized input, or test HTTP DNS, TCP, TLS, and authentication in layers.
- 03Compare one variableCapture initialize negotiation and the selected protocol version.
- 04Record decisive evidenceRun tools/list, inspect the required schema, then invoke one read-only tool.
codex mcp list --json 2>/dev/null || true
codex doctor --summary 2>/dev/null || true
claude mcp list 2>/dev/null || true
# 再分别使用 codex mcp get <name> 或 claude mcp get <name>。
# stdio 服务只运行可信命令的 --help，不执行来源不明的安装管道。
Apply the fix at the confirmed root cause
Make the smallest change that addresses the proven layer. Avoid hiding deterministic configuration failures behind broad retries or disabled validation.
- 01Correct the failing layerCorrect the executable, arguments, cwd, environment, URL, and transport in the authoritative scope.
- 02Restore required behaviorSend stdio logs to stderr and reserve stdout for protocol frames.
- 03Remove temporary workaroundsAlign protocol version and authentication, then grant only the minimum tool permissions.
1. client list/get 能读取最终配置
2. server process 或 HTTP endpoint 可达
3. initialize 与 tools/list 成功
4. 一个只读工具返回预期结构
5. 日志无 token、项目秘密和协议污染Verify the repair, not just one successful call
Repeat the original path after the minimal check succeeds, then verify stable behavior under normal streaming, concurrency, and timeout conditions.
- stdio stdout contains protocol messages only.
- Client and server negotiate a compatible protocol version.
- The expected tool names and schemas appear in tools/list.
- A read-only tool succeeds before any write or destructive capability is enabled.
Security boundaries and escalation evidence
Collect enough evidence to reproduce and escalate the failure without exposing credentials or weakening transport, permission, and validation controls.
- Do not place secrets directly in committed MCP configuration.
- Treat third-party MCP servers and tool output as untrusted input.
- Start with read-only filesystem and network scope.
- Escalate with client/server versions, sanitized config, stderr, initialize result, and tool-list output.
Official sources and verification scope
This guide is grounded in protocol specifications and official client documentation. Error text, retry headers, and configuration fields may change by service or client version; verify the sources and redact logs and request samples before sharing.
Read the verification methodology