Remote MCP Adapter

Remote MCP servers are great until a tool needs a real file. Put an MCP server in Docker, Kubernetes, or on another machine and local file paths stop making sense. Remote MCP Adapter sits in the middle, handles uploads and generated files properly, and adds the session and tool-surface safeguards you usually want once this is running for real.

Most MCP servers were written assuming the client and server share a filesystem. Move a server into Docker, Kubernetes, or a remote machine and two things break immediately:

1. File inputs break. A tool receives a local path from the client, but the server cannot read it.
2. File outputs break. A tool writes a screenshot or PDF on the server, but the client cannot get it back.

Remote MCP Adapter sits between your client and your upstream MCP servers. It fixes those file-path breaks without turning the rest of the stack upside down.

• your MCP client and upstream server run on different machines or in different containers
• your tools need uploads, screenshots, PDFs, downloads, or other filesystem-backed behavior
• you want one gateway in front of multiple upstream MCP servers

• the client and upstream already safely share a filesystem
• your upstream tools do not touch files at all

Once the demo stack is up, point your agent at the adapter and try this:

Go to https://www.csm-testcenter.org/ and upload the readme of our repo there.
Take a screenshot for evidence and report back once done.
Also give me the download URL for the screenshot.

This exercises the whole failure path in one go: upload from the client, use that file on the server, generate a screenshot there, and get the result back. Without an adapter, that chain usually breaks somewhere in the middle.

The repo ships 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

curl http://localhost:8932/healthz

Requires Python 3.12+ and uv.

git clone https://github.com/aakashH242/remote-mcp-adapter.git
cd remote-mcp-adapter
uv sync
# config.local.yaml has upstream.url set to http://localhost:8931/mcp
uv run remote-mcp-adapter --config config.local.yaml

Start Playwright MCP in a second terminal (requires Node.js):

npx @playwright/mcp --headless --port 8931

GitHub Copilot — add to mcp.json:

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

OpenAI Codex — add to config.toml:

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

Antigravity — add to mcp_config.json:

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

These add operational depth once you move past the local demo. The adapter is not just a file bridge; it also gives you controls for safer routing, safer model-visible tool metadata, and safer storage.

• Sessions. Every client connection is identified by Mcp-Session-Id. The adapter scopes uploads, artifacts, and quotas to that session automatically, and when adapter auth is enabled it binds stateful requests to the same adapter auth context that established the session.

• Upload handles. The agent calls <server_id>_get_upload_url(...), POSTs the file, and gets an upload://sessions/<sid>/<upload_id> handle. The adapter resolves it to a real path before forwarding upstream. Set core.public_base_url in any deployment behind a reverse proxy, ingress, or load balancer so returned URLs point at your actual external address.

• Artifact references. When a configured artifact-producer tool writes a file, the adapter captures it and returns an artifact://sessions/<sid>/<artifact_id>/<filename> URI. The agent calls resources/read on that URI to get the bytes back.

servers:
  - id: "playwright"
    mount_path: "/mcp/playwright"
    upstream:
      url: "http://localhost:8931/mcp"

    adapters:
      - type: "upload_consumer"
        tools: ["browser_file_upload"]
        file_path_argument: "paths"

      - type: "artifact_producer"
        tools: ["browser_take_screenshot", "browser_pdf_save"]
        output_path_argument: "filename"
        output_locator:
          mode: "regex"

servers[] is the only required section. Everything else has safe defaults. The full config.yaml.template documents every field inline.

When adapters are enabled, the adapter and the upstream servers must share a common directory — either via local filesystem or network storage.

You can deploy the adapter in a few different ways depending on your environment:

• Docker Compose for local end-to-end testing
• Docker image for simple container deployment
• Helm chart for Kubernetes deployments via the published Helm repository

Create your configuration using the config reference, ensure your upstream servers are running, and make sure the adapter and upstreams share the same storage path configured by storage.root. If clients will use <server_id>_get_upload_url(...) or HTTP artifact download links through a hostname, proxy, ingress, or load balancer, set core.public_base_url to that external base URL. Otherwise the adapter may generate URLs that only make sense inside the container or pod network.

For Kubernetes, use the published Helm repository:

• https://aakashh242.github.io/remote-mcp-adapter

That is the repository URL Helm expects for helm repo add, because it is the GitHub Pages root where index.yaml is published. The source chart lives in charts/remote-mcp-adapter if you want to inspect or contribute to it, but that source folder is not the primary end-user install path.

Example Helm install flow:

helm repo add remote-mcp-adapter https://aakashh242.github.io/remote-mcp-adapter
helm repo update
helm upgrade --install remote-mcp-adapter remote-mcp-adapter/remote-mcp-adapter \
  --namespace remote-mcp-adapter \
  --create-namespace \
  -f values.yaml

For Kubernetes deployment shapes, overlay patterns, and production-oriented examples, see:

• Deployment docs
• Deploy with Helm

For a direct container deployment, pull and run the image:

docker pull ghcr.io/aakashH242/remote-mcp-adapter:latest

docker run -d -v ./shared:/<your-path> -v ./config.yaml:/etc/remote-mcp-adapter/config.yaml -p 8932:8932 ghcr.io/aakashH242/remote-mcp-adapter:latest

Full documentation lives in the MkDocs site:

For maintainers, the repo-root SECURITY.md tracks the security controls and trust boundaries that are already implemented.

MIT