Remote MCP Adapter

What is 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. It sits between your client and upstream MCP servers, staging uploaded files so tools can read them and returning output files as downloadable artifacts, while forwarding everything else unchanged.

How to use Remote MCP Adapter?

Run via Docker Compose (docker compose up on port 8932) or from source with Python 3.12+ and uv (uv run remote-mcp-adapter --config config.yaml). Configure your IDE or agent to point to the adapter's URL (e.g., http://localhost:8932/mcp/playwright) as an HTTP MCP server.

Key features of Remote MCP Adapter

• Multiserver relay: expose multiple upstream MCP servers under one gateway.
• File uploads via upload:// handles and outputs as artifact:// resources.
• Per-session isolation with TTL cleanup and optional revival.
• State backends: in-memory, SQLite, or Redis.
• Upstream health checks and circuit breaker for resilience.
• Bearer token auth and signed one-time upload URLs.

Use cases of Remote MCP Adapter

• Run MCP servers in containers or remote machines without a shared filesystem.
• Allow tools to read client-side files through staged upload handles.
• Capture tool-generated files (screenshots, PDFs) as downloadable MCP artifacts.
• Expose multiple upstream MCP servers under one gateway with session isolation.

FAQ from Remote MCP Adapter

What problem does Remote MCP Adapter solve?

It bridges the gap when MCP servers run remotely: tools that read local files can't reach client files, and tools that write files save them on the server where the client can't retrieve them. The adapter stages uploads and captures outputs to solve both issues.

What are the runtime requirements?

Python 3.12+ and uv for source installation, or Docker Compose for containerized deployment.

What state backends are supported?

In-memory (for development), SQLite (single node), or Redis (multi-node).

How does authentication work?

The adapter uses bearer tokens for clients and supports signed, one-time upload URLs for file staging.

Can it handle multiple upstream servers?

Yes. The adapter supports a multiserver relay, exposing each upstream server under its own path (e.g., /mcp/playwright, /mcp/screenshot).