Files

T

retoor 251c3dc2ba research: mcp-client-support subject (106 sources, 3 conclusions)

- wire spec: lifecycle, stdio + Streamable HTTP transports, tools,
  utilities, legacy SSE, versioning, changelog (14 Tier 1)
- client ecosystem: Claude Code/VS Code/Cursor/Codex configs,
  mcp-remote, Smithery, registries, Glama (12 Tier 1)
- security/ops: authorization draft, trust model, poisoning,
  rug pulls, production hardening (12 Tier 1) + 68 Tier 2 cards
- conclusions: minimal stdlib client on 2025-11-25, normalizer +
  resolver agent for pasted configs/GitHub URLs, untrusted-until-
  consent trust model; nothing built yet
- audit PASS (14 subjects, 797 sources, 32 conclusions)

2026-10-18 19:23:02 +02:00

4.1 KiB

Raw Blame History

mcp-remote README (stdio to HTTP bridge)

Metadata

Field	Value
Institute	Molodetz Institute - Research and Retrieval Division
Subject	mcp-client-support
Document type	Source Dossier
Tier	1
Source title	mcp-remote README
Source URL	https://github.com/punkpeye/mcp-remote
Source publisher / author	Repository maintainers (originally Glen Maddern / geelen)
Source type	repository
Source date (published)	Unknown, not stated
Date researched	2026-10-18
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	gather-subagent direct page fetch, parent synthesis from evidence pack
Confidence	Medium
Status	Active

Summary

README of mcp-remote, the standard one-liner bridge that lets stdio-only MCP clients reach remote servers: {"command": "npx", "args": ["mcp-remote", "https://remote.mcp.server/sse"]}. It documents header auth (--header, --header-file), a no-spaces args workaround for a client escaping bug, tool filtering, OAuth session handling, and transport selection. The requested geelen/mcp-remote URL redirected to punkpeye/mcp-remote at fetch time.

Key findings

Purpose: "Most are stdio-only, and those that do support HTTP+SSE don't yet support the OAuth flows required. That's where mcp-remote comes in... drop in this one liner": {"command": "npx", "args": ["mcp-remote", "https://remote.mcp.server/sse"]}.
"To bypass authentication, or to emit custom headers on all requests to your remote server, pass --header CLI arguments" ("Authorization: Bearer ${AUTH_TOKEN}", token via env); secrets-in-argv avoided with --header-file ("One Name: value per line; # starts a comment").
Known client bug: "Cursor, Codex-Cli and Claude Desktop (Windows) have a bug where spaces inside args aren't escaped... work around it" with "Authorization:${AUTH_HEADER}" ("note no spaces around ':'").
--ignore-tool "will filter out tools matching the specified patterns from both tools/list responses and block tools/call requests. Supports wildcard patterns with *", repeatable; --resource isolates OAuth sessions for multi-instance use ("Each unique combination of server URL, resource, custom headers, and --authorize-param values" gets separate token storage).
OAuth: browser flow with derived ports ("somewhere in 3335-49150"), --host/--callback-path/--auth-timeout/--static-oauth-client-info/--static-oauth-client-metadata (for servers without dynamic client registration); credentials in ~/.mcp-auth ("or wherever your MCP_REMOTE_CONFIG_DIR points to") under mcp-remote-v1 layout.
--transport http-first (default) / sse-first / http-only / sse-only; --protocol auto makes it a dual-era client against 2026-07-28 servers; --allow-http only "in secure private networks".
Redirect observation: requested https://github.com/geelen/mcp-remote, served as https://github.com/punkpeye/mcp-remote. Do not rely on the geelen path going forward.

Pros / strengths

The de facto standard recipe for remote-to-stdio conversion, stated as a copy-paste one-liner with auth variants.
Documents real client bugs (args space escaping) with an exact workaround, which is precisely the kind of generator rule that is otherwise learned by breakage.
OAuth surface (ports, static client metadata, token storage layout) is unusually complete for a README.

Cons / limitations / caveats

Current maintenance home is unverified: geelen/mcp-remote was observed resolving to punkpeye/mcp-remote, but whether this is a rename, transfer, or fork was not verified.
No publish date; flag surface may have drifted since the fetch.
Community-maintained bridge, not a vendor contract: behavior claims rest on README authority alone.

Relevance to tai

The standard recipe for converting a remote URL into a runnable stdio entry: npx mcp-remote <url> --header ..., including the no-spaces workaround a generator must emit for affected clients. Directly load-bearing for tai's remote-server resolution path.

Changelog

Date	Change
2026-10-18	Initial dossier created.

4.1 KiB Raw Blame History