Skip to content

docs: explain stdio vs Streamable HTTP in the root README #5276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cliffhall merged 4 commits into from
Oct 25, 2026
Merged

docs: explain stdio vs Streamable HTTP in the root README #5276

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8303e32
docs: explain stdio vs Streamable HTTP in the root README
cliffhall Oct 25, 2026
9d8fc87
docs: move the Transports section after Using an MCP Client
cliffhall Oct 25, 2026
35a0074
docs: say the servers can be started with npx/uvx, not used directly
cliffhall Oct 25, 2026
f26c4f7
docs: drop the archived github server from the client config example
cliffhall Oct 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 26 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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": "<YOUR_TOKEN>"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
Expand All @@ -133,6 +126,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.
Expand Down
Loading