docs: clarify MCP setup when proxy /mcp is unavailable

[SvenMeyer]

Summary

The MCP docs currently imply that headroom proxy can be used as an HTTP MCP endpoint at /mcp, but with the current installed package this endpoint returns 404 while the stdio MCP server works.

Environment

• headroom, version 0.21.32
• Linux Manjaro
• Two local proxy instances:
  • default proxy: http://127.0.0.1:8787
  • Azure/LiteLLM proxy: http://127.0.0.1:8788

What works

The proxies are healthy:

curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8788/health

The stdio MCP server works when pointed at either proxy:

{
  "mcpServers": {
    "headroom": {
      "type": "stdio",
      "command": "headroom",
      "args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8787"]
    },
    "headroom-azure": {
      "type": "stdio",
      "command": "headroom",
      "args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8788"]
    }
  }
}

Both expose:

• headroom_compress
• headroom_retrieve
• headroom_stats

What does not work

The HTTP MCP endpoint is not available on either proxy:

curl -i http://127.0.0.1:8787/mcp
curl -i http://127.0.0.1:8788/mcp

Both return 404 Not Found.

Documentation concern

The docs at https://headroom-docs.vercel.app/docs/mcp and the llms docs mention proxy-backed MCP in a way that makes it easy to configure MCP clients as:

{
  "headroom-azure": {
    "type": "http",
    "url": "http://localhost:8788/mcp"
  }
}

That configuration fails for the current CLI behavior.

Suggested fix

Clarify that for headroom 0.21.32, MCP clients should use stdio:

headroom mcp serve --proxy-url http://127.0.0.1:<proxy-port>

and only use HTTP /mcp if/when the installed proxy version explicitly exposes that endpoint.

[Baijack-star]

This is a good docs bug. I would make the fix explicit enough that users do not infer transport support from the proxy health endpoint.

Suggested wording for the MCP docs:

## Current transport support

For `headroom 0.21.32`, MCP is exposed by the stdio server:

```json
{
  "mcpServers": {
    "headroom": {
      "type": "stdio",
      "command": "headroom",
      "args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8787"]
    }
  }
}
```

Do not configure `http://127.0.0.1:8787/mcp` unless your installed version explicitly documents an HTTP MCP endpoint. A healthy proxy at `/health` only proves the compression proxy is running; it does not imply that `/mcp` is mounted.

I would also add a tiny verification table:

Check	Expected
curl http://127.0.0.1:8787/health	proxy is healthy
headroom mcp serve --proxy-url http://127.0.0.1:8787	stdio MCP server starts
curl -i http://127.0.0.1:8787/mcp	may be 404 unless HTTP MCP is implemented/enabled

That separates proxy readiness from MCP transport readiness, which is the confusion this issue exposed.

[JeanLuX]

Thank you. I've been desperately trying to get this MCP endpoint to work for several hours now because of what's written in the documentation, but now I know why it isn't working: it simply doesn't exist.

For anyone who might find this useful: if you are using pyenv, you can add the following to your MCP configuration (I am using Zoo Code):

"headroom": {
    "type": "stdio",
    "command": "bash",
    "args": [
        "-lc",
        "PYENV_VERSION=3.13 pyenv exec headroom mcp serve --proxy-url http://127.0.0.1:8787"
    ]
}

[Ooroot-lab]

I am in a remote MCP environment. How can I use Headroom commands locally? Since it is a remote environment, I need an HTTP transmission method. How can using the stdio method be a solution to the problem where HTTP transmission cannot be used?