From 8303e32ec515c782729a1bf3881776de04bbb651 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sun, 25 Oct 2026 00:11:14 -0400 Subject: [PATCH 1/4] docs: explain stdio vs Streamable HTTP in the root README A newcomer running `uvx mcp-server-git` sees it open no port and appear to hang, and the README never says why. Add a Transports section after the install commands: what each transport is, that every server here serves stdio and only everything also serves Streamable HTTP, how to try either with the Inspector, and where the MCP docs cover transports. Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: cliffhall --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 9c388c80a4..218c8cc9c7 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,30 @@ 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`. +### Transports: stdio and Streamable HTTP + +An MCP server talks to its client over a **transport**. The protocol defines two standard ones, and they run very differently: + +| Transport | How the server runs | How a client reaches it | +|---|---|---| +| **stdio** | The client launches the server as a subprocess and talks to it over the process's stdin and stdout. The server opens no port. | A `command` and `args` in the client's configuration, as in the examples below | +| **Streamable HTTP** | The server runs on its own as an HTTP service, and can serve many clients | A URL, such as `http://localhost:3001/mcp` | + +**Every server in this repository serves stdio, and only [Everything](src/everything) also serves Streamable HTTP** (its README shows how to start it that way, and covers its deprecated HTTP+SSE transport too). So when you run `uvx mcp-server-git` or `npx -y @modelcontextprotocol/server-memory` in a terminal, it opens no port, prints at most a one-line startup notice, and then appears to hang. That is expected: it is waiting for a client to send it messages on stdin. You do not normally start a stdio server yourself; your MCP client starts it from its configuration and stops it when it is done. + +To try a server without setting up a client, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). Given a stdio server's command, it launches the server for you and lets you browse and call its tools; given a URL, it connects to a running Streamable HTTP server: + +```sh +# A stdio server: the Inspector launches it +npx @modelcontextprotocol/inspector uvx mcp-server-git + +# A Streamable HTTP server: start it first, then connect to its URL +npx @modelcontextprotocol/server-everything streamableHttp +npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3001/mcp +``` + +For more, see the [transport layer](https://modelcontextprotocol.io/docs/learn/architecture#transport-layer) in the MCP architecture overview, and [Transports](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) in the specification. + ### 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: From 9d8fc8762ccbf7d9da02b9f8fda9390f28a439aa Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sun, 25 Oct 2026 00:44:38 -0400 Subject: [PATCH 2/4] docs: move the Transports section after Using an MCP Client Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: cliffhall --- README.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 218c8cc9c7..631d696288 100644 --- a/README.md +++ b/README.md @@ -76,30 +76,6 @@ 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`. -### Transports: stdio and Streamable HTTP - -An MCP server talks to its client over a **transport**. The protocol defines two standard ones, and they run very differently: - -| Transport | How the server runs | How a client reaches it | -|---|---|---| -| **stdio** | The client launches the server as a subprocess and talks to it over the process's stdin and stdout. The server opens no port. | A `command` and `args` in the client's configuration, as in the examples below | -| **Streamable HTTP** | The server runs on its own as an HTTP service, and can serve many clients | A URL, such as `http://localhost:3001/mcp` | - -**Every server in this repository serves stdio, and only [Everything](src/everything) also serves Streamable HTTP** (its README shows how to start it that way, and covers its deprecated HTTP+SSE transport too). So when you run `uvx mcp-server-git` or `npx -y @modelcontextprotocol/server-memory` in a terminal, it opens no port, prints at most a one-line startup notice, and then appears to hang. That is expected: it is waiting for a client to send it messages on stdin. You do not normally start a stdio server yourself; your MCP client starts it from its configuration and stops it when it is done. - -To try a server without setting up a client, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). Given a stdio server's command, it launches the server for you and lets you browse and call its tools; given a URL, it connects to a running Streamable HTTP server: - -```sh -# A stdio server: the Inspector launches it -npx @modelcontextprotocol/inspector uvx mcp-server-git - -# A Streamable HTTP server: start it first, then connect to its URL -npx @modelcontextprotocol/server-everything streamableHttp -npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3001/mcp -``` - -For more, see the [transport layer](https://modelcontextprotocol.io/docs/learn/architecture#transport-layer) in the MCP architecture overview, and [Transports](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) in the specification. - ### 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: @@ -157,6 +133,30 @@ Additional examples of using the Claude Desktop as an MCP client might look like On Windows, apply the same wrapper to each `npx`-based entry above by changing `"command"` to `"cmd"` and prepending `"/c", "npx"` to the existing `args`. Leave `uvx` entries unchanged. +### Transports: stdio and Streamable HTTP + +An MCP server talks to its client over a **transport**. The protocol defines two standard ones, and they run very differently: + +| Transport | How the server runs | How a client reaches it | +|---|---|---| +| **stdio** | The client launches the server as a subprocess and talks to it over the process's stdin and stdout. The server opens no port. | A `command` and `args` in the client's configuration, as in the examples above | +| **Streamable HTTP** | The server runs on its own as an HTTP service, and can serve many clients | A URL, such as `http://localhost:3001/mcp` | + +**Every server in this repository serves stdio, and only [Everything](src/everything) also serves Streamable HTTP** (its README shows how to start it that way, and covers its deprecated HTTP+SSE transport too). So when you run `uvx mcp-server-git` or `npx -y @modelcontextprotocol/server-memory` in a terminal, it opens no port, prints at most a one-line startup notice, and then appears to hang. That is expected: it is waiting for a client to send it messages on stdin. You do not normally start a stdio server yourself; your MCP client starts it from its configuration and stops it when it is done. + +To try a server without setting up a client, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). Given a stdio server's command, it launches the server for you and lets you browse and call its tools; given a URL, it connects to a running Streamable HTTP server: + +```sh +# A stdio server: the Inspector launches it +npx @modelcontextprotocol/inspector uvx mcp-server-git + +# A Streamable HTTP server: start it first, then connect to its URL +npx @modelcontextprotocol/server-everything streamableHttp +npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3001/mcp +``` + +For more, see the [transport layer](https://modelcontextprotocol.io/docs/learn/architecture#transport-layer) in the MCP architecture overview, and [Transports](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) in the specification. + ## 🛠️ Creating Your Own Server Interested in creating your own MCP server? Visit the official documentation at [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) for comprehensive guides, best practices, and technical details on implementing MCP servers. From 35a00748df5818fd707cfea72c57e47cf4e47958 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sun, 25 Oct 2026 00:58:07 -0400 Subject: [PATCH 3/4] docs: say the servers can be started with npx/uvx, not used directly Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: cliffhall --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 631d696288..02245974d6 100644 --- a/README.md +++ b/README.md @@ -55,14 +55,14 @@ The following reference servers are now archived and can be found at [servers-ar ## 🚀 Getting Started ### Using MCP Servers in this Repository -TypeScript-based servers in this repository can be used directly with `npx`. +TypeScript-based servers in this repository can be started with `npx`. For example, this will start the [Memory](src/memory) server: ```sh npx -y @modelcontextprotocol/server-memory ``` -Python-based servers in this repository can be used directly with [`uvx`](https://docs.astral.sh/uv/concepts/tools/) or [`pip`](https://pypi.org/project/pip/). `uvx` is recommended for ease of use and setup. +Python-based servers in this repository can be started with [`uvx`](https://docs.astral.sh/uv/concepts/tools/) or [`pip`](https://pypi.org/project/pip/). `uvx` is recommended for ease of use and setup. For example, this will start the [Git](src/git) server: ```sh From f26c4f7bd49465025fe1ddf6cbdda3a57ed9ba4a Mon Sep 17 00:00:00 2001 From: cliffhall Date: Sun, 25 Oct 2026 00:59:01 -0400 Subject: [PATCH 4/4] docs: drop the archived github server from the client config example Co-Authored-By: Claude Opus 5.5 (1M context) Signed-off-by: cliffhall --- README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/README.md b/README.md index 02245974d6..94d422542a 100644 --- a/README.md +++ b/README.md @@ -116,13 +116,6 @@ Additional examples of using the Claude Desktop as an MCP client might look like "command": "uvx", "args": ["mcp-server-git", "--repository", "path/to/git/repo"] }, - "github": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-github"], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "" - } - }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]