confusing documentation

[sirus20x6]

I have an application that expects mcp to be on port 3001 over sse. the documentation tells me how to create the config.json alright, but then it goes into if I want to make a server, or a client, or this or that which I do not want to do. what I want to do is to run mcp so it's available at that port, but I'm not even sure what to run. the documentation doesn't even really go into anything useful. somehow I stumbled on the model inspector

it also seems to be able to talk to mcp on port 3001, but no dice. where is the binary? what do I run? where do I set the port? do I make a systemd service to start something? how does mcp run? in fact I don't even know where to put the config.json.

on the git page I see "For example, this will start the Git server:

With uvx

uvx mcp-server-git" but running uvx mcp-server-git doesn't seem to do anything, there is no output, there are no ports opened.... it just sits there.

[dracoshub]

Actually I am going to agree with this post. The documentation concerning the setting of ports for the MCP Servers presumes some background in nodejs conventions and or python and its unlikely nost people have boht. I too find it difficult to know why specifiying the port is never mentioned when a major goal is to run mulitple tools or MCP servers at once.

[NaimalArain13]

Hi! I reproduced this exact behavior today and want to share what I found,
and also offer to put together a PR to fix the docs.

What's actually happening:

When you run uvx mcp-server-git and it "just sits there" — that's correct
behavior, not a bug. MCP servers using the default stdio transport are not
standalone services. They don't open any port and they produce no terminal
output because they're designed to be spawned as a subprocess by an MCP
client (like Claude Desktop), not run manually by a human.

The server is silently waiting for a JSON-RPC message on stdin. You can
verify this yourself:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | uvx mcp-server-git

You'll get a proper JSON response back — the server is alive and working perfectly.

The two transport modes the docs don't clearly distinguish:

• stdio (default) — server communicates over stdin/stdout, spawned as a
  subprocess by the client. No port, no output. This is what mcp-server-git uses.
• SSE — server runs as an HTTP service and exposes a network endpoint
  (like port 3001). This is what you'd use for remote/network servers.

If you want to visually interact with a stdio server without a full client
setup, the MCP Inspector does exactly that:

npx @modelcontextprotocol/inspector uvx mcp-server-git

It opens at localhost:6274, spawns the server as a subprocess automatically,
and lets you call tools interactively.

What I think the docs need:

A clear "How MCP Servers Actually Run" section that explains:

1. The stdio vs SSE transport distinction upfront
2. Why running a stdio server manually appears to do nothing
3. That config.json tells your MCP client to spawn the server — you don't
   run it yourself
4. The MCP Inspector as the go-to tool for testing servers locally

I'd be happy to write this up as a PR if maintainers think it would help.
Would a new section in the README work, or is there a preferred docs location?

[zuhabul]

Opened a docs clarification PR from @zuhabul: https://github.com/modelcontextprotocol/servers/pull/4128\n\nIt adds an explicit stdio behavior section, initialize sanity-check command, and inspector debugging guidance.