Remote MCP Adapter

An MCP gateway that makes remote servers feel local — it manages file uploads to tools and captures generated files back to the client.

The Model Context Protocol supports remote servers over Streamable HTTP. But most MCP servers were built assuming the client and server share a filesystem. When you move a server to a container or a remote machine, two things break: tools that read local files can't reach files on the client's machine, and tools that write files (screenshots, PDFs) save them on the server where the client can't retrieve them.

This adapter sits between your client and your upstream MCP servers. It stages uploaded files so tools can read them, captures tool output files as artifacts the client can read back, and forwards everything else unchanged.

Key Features

• 🌐 Multiserver relay - Expose multiple upstream MCP servers under one gateway (/mcp/<server>).
• ⬆️ File uploads - Stage client files and pass them to tools via upload://... handles.
• 📬 File outputs - Capture screenshots, PDFs, and more, returning them as artifact://... MCP resources with optional download links.
• ⏳ Sessions - Provide per-session isolation, TTL cleanup, and optional “revival” on reconnect.
• 💾 State backends - Use in-memory (dev), SQLite (single node), or Redis (multi-node).
• 💓 Upstream health - Perform active checks and implement a circuit breaker to prevent cascading failures.
• 🔁 Resilience - Retry and reconnect when upstream sessions drop.
• 🔒 Auth - Use bearer tokens and signed, one-time upload URLs.
• 📊 Observability - Collect OpenTelemetry metrics with optional log export.
• 🛡️ Safe storage - Ensure atomic writes, orphan cleanup, and enforce quota limits.

Getting started

Docker Compose (recommended)

The repo includes a compose.yaml that starts Playwright MCP on port 8931 and the adapter on port 8932.

git clone https://github.com/aakashH242/remote-mcp-adapter.git
cd remote-mcp-adapter
docker compose up --build

Verify the adapter is running:

curl http://localhost:8932/healthz

From source

Requires Python 3.12+ and uv.

git clone https://github.com/aakashH242/remote-mcp-adapter.git
cd remote-mcp-adapter
uv sync
uv run remote-mcp-adapter --config config.yaml

Configure in IDE/Agent

OpenAI Codex

Add the adapter in config.toml.

[mcp_servers.playwright]
url = "http://localhost:8932/mcp/playwright"

GitHub Copilot

Add the adapter in mcp.json.

{
	"servers": {
      "playwright": {
        "url": "http://localhost:8932/mcp/playwright",
			"type": "http"
      }
    }
    
}

Antigravity

Add the adapter in mcp_config.json.

{
    "mcpServers": {
        "playwright": {
            "serverUrl": "http://localhost:8932/mcp/playwright"
        }
    }
}

Documentation

Full documentation lives in the MkDocs site:

License

MIT