Remote MCP Adapter
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:
| 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
Server Config
{
"_comments": "Docker Compose (recommended) - See ReadME at https://github.com/aakashh242/remote-mcp-adapter",
"mcpServers": {
"mcpAdapter": {
"url": "http://localhost:8932/mcp/playwright"
}
}
}Recommend Servers
View AllPlaywright MCP server
A Serper MCP Server