Resolving Paper MCP Connectivity in Docker Dev Containers

How to Use Paper MCP Server Inside a Dev Container

Paper MCP servers strictly bind to 127.0.0.1 on the host, causing immediate ECONNRESET errors when accessed from within a Docker-based dev container. Standard Docker port mapping fails in this scenario because it only exposes container ports to the host, whereas the client requires the reverse traffic flow.

Why This Matters

The technical reality of network isolation in Docker means that containerized tools cannot natively distinguish between the host’s loopback and their own. While ideal development models suggest simple port mapping, security-hardened services like Paper MCP reject connections from the Docker bridge gateway (e.g., 172.20.0.1), necessitating a relay that makes traffic appear local to the host.

Key Insights

• ECONNRESET errors occur because Paper MCP only accepts connections from 127.0.0.1 on the host (Thales Augusto, 2026).
• Standard Docker port forwarding (29979:29979) is directional and fails to facilitate the necessary container-to-host communication path.
• A two-hop socat relay effectively masks the container gateway IP, presenting the request to Paper as if it originated from the host’s own localhost.
• Dynamic gateway resolution is required in host-side scripts to ensure the relay binds to the correct Docker bridge network IP (e.g., using docker network inspect).
• Persisting the relay via systemd user services ensures the bridge remains active across reboots and handles container restarts automatically.

Working Examples

Installing socat in the .devcontainer/Dockerfile

USER root
RUN apt-get update && apt-get install -y --no-install-recommends socat && rm -rf /var/lib/apt/lists/*

Configuring the in-container relay via Docker Compose

services:
  rails-app:
    command: >
      /bin/sh -c "socat TCP-LISTEN:29979,fork,reuseaddr
      TCP:$$(ip route show default | awk '{print $$3}'):29979
      & sleep infinity"

Host-side relay script to bridge Paper MCP

#!/bin/bash
NETWORK_NAME="your_project_default"
while true; do
  DOCKER_GW=$(docker network inspect "$NETWORK_NAME" --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}' 2>/dev/null)
  if [ -n "$DOCKER_GW" ]; then break; fi
  sleep 3
done
exec socat TCP-LISTEN:29979,fork,reuseaddr,bind="$DOCKER_GW" TCP:127.0.0.1:29979

Practical Applications

• Development in VS Code Dev Containers or Cursor where MCP tools need to access host-resident AI servers.
• Pitfall: Using 127.0.0.1 in the host-side socat bind address instead of the Docker gateway IP, which prevents the container from reaching the relay.
• Implementing dynamic port forwarding for services that lack native CIDR-based access control lists.
• Pitfall: Forgetting to escape the ’$’ character in Docker Compose command strings, leading to shell execution errors inside the container.

References:

• https://dev.to/tarv7/how-to-use-paper-mcp-server-inside-a-dev-container-2324