From 2ee1cc0f476b3c738bb0adc544673db3067279e7 Mon Sep 17 00:00:00 2001 From: Tanishka Marrott Date: Sat, 2 May 2026 19:36:29 +0530 Subject: [PATCH] docs: explain how MCP servers actually launch (stdio vs SSE, Inspector) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes a recurring point of confusion (#521): developers run `uvx mcp-server-git` directly, see no output, and think the server is broken. Added a new 'Understanding How Servers Are Launched' subsection that explains: - stdio servers wait on stdin — appearing to hang is expected - the MCP client spawns the server; you don't run it yourself - stdio vs SSE/HTTP transport comparison table - MCP Inspector as the recommended local testing tool Co-Authored-By: Claude Sonnet 4.6 --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 874916cab3..4d0d4de4e5 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,27 @@ python -m mcp_server_git Follow [these](https://docs.astral.sh/uv/getting-started/installation/) instructions to install `uv` / `uvx` and [these](https://pip.pypa.io/en/stable/installation/) to install `pip`. +### Understanding How Servers Are Launched + +MCP servers communicate over **stdio** (stdin/stdout) by default. If you run a server like `uvx mcp-server-git` directly in your terminal, it will appear to hang — it is waiting for a client to connect over stdin and send JSON-RPC messages. This is expected behaviour, not a bug. + +**You do not run MCP servers yourself.** Your MCP client (Claude Desktop, VS Code, Cursor, etc.) reads its config file and spawns the server process automatically. The client and server communicate over the spawned process's stdin/stdout. When you close the client, the server process stops. + +**Two transport modes:** + +| Transport | How the server runs | When to use | +|---|---|---| +| **stdio** (default) | Client spawns the server as a subprocess; communication is over stdin/stdout | Local servers — all reference servers in this repo | +| **SSE / HTTP** | Server runs as a standalone HTTP service; client connects over a network URL | Remote or shared servers | + +**Testing a server without a full client setup:** use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): + +```sh +npx @modelcontextprotocol/inspector uvx mcp-server-git +``` + +The Inspector opens a browser UI that lets you browse available tools, invoke them, and inspect responses — no LLM or client configuration required. It is the recommended way to verify a server works before wiring it into a client. + ### Using an MCP Client However, running a server on its own isn't very useful, and should instead be configured into an MCP client. For example, here's the Claude Desktop configuration to use the above server: