Skip to content

docs: clarify stdio server behavior and debugging#4128

Open
zuhabul wants to merge 1 commit into
modelcontextprotocol:mainfrom
zuhabul:docs/clarify-stdio-server-behavior
Open

docs: clarify stdio server behavior and debugging#4128
zuhabul wants to merge 1 commit into
modelcontextprotocol:mainfrom
zuhabul:docs/clarify-stdio-server-behavior

Conversation

@zuhabul
Copy link
Copy Markdown

@zuhabul zuhabul commented May 9, 2026

Summary

  • add a new README section explaining why running uvx mcp-server-git appears idle
  • clarify stdio transport semantics (no port, no standalone daemon behavior)
  • add a manual initialize command for quick liveness checks
  • add MCP Inspector usage for interactive debugging

Why

  • addresses recurring confusion captured in confusing documentation #521
  • makes first-time setup and debugging significantly clearer for contributors

Closes #521

Add a new section explaining why uvx-launched servers can appear idle, how stdio transport works, how to sanity-check with initialize JSON-RPC, and how to debug with MCP Inspector.

Closes modelcontextprotocol#521

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings May 9, 2026 22:11
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the repository’s top-level documentation to reduce confusion when running MCP servers directly (especially stdio-based servers that appear “idle” when launched without a client), and to provide quick debugging/liveness-check workflows.

Changes:

  • Adds a README section explaining why uvx mcp-server-git typically shows no output and opens no port (stdio transport behavior).
  • Documents a manual initialize JSON-RPC request to sanity-check server liveness.
  • Adds an MCP Inspector command for interactive debugging and clarifies when to use network transports (e.g., HTTP/SSE).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@MukundaKatta
Copy link
Copy Markdown

+1 to the manual initialize liveness check idea. The MCP Inspector pointer
is also gold for first-time setup. One small ask: if there's room, a
copy-pastable jq filter showing just serverInfo.name + version would help
new contributors confirm the handshake at a glance without parsing the
full JSON response.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

confusing documentation

3 participants