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. ``bash git clone https://github.com/aakashH242/remote-mcp-adapter.git cd remote-mcp-adapter docker compose up --build ` Verify the adapter is running: `bash curl http://localhost:8932/healthz `

From source

Requires Python 3.12+ and uv. `bash 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. `toml [mcp_servers.playwright] url = "http://localhost:8932/mcp/playwright" ` GitHub Copilot Add the adapter in mcp.json. `json { "servers": { "playwright": { "url": "http://localhost:8932/mcp/playwright", "type": "http" } } } ` Antigravity Add the adapter in mcp_config.json. `json { "mcpServers": { "playwright": { "serverUrl": "http://localhost:8932/mcp/playwright" } } } ` ---

Documentation

Full documentation lives in the MkDocs site: | Page | What it covers | |---|---| | Getting Started | Run the adapter in under 5 minutes | | Core Concepts | Sessions, upload:// handles, artifact:// references | | How It Works | Tool buckets, request flow diagram | | Configuration | Quick config guide with examples | | Config Reference | Every field and default | | Security | Auth setup and upload URL signing | | Telemetry | OpenTelemetry metrics catalog | | Health | /healthz` semantics and example payloads | | Troubleshooting | Common problems and fixes | ---

License

MIT