McpSidecar

McpSidecar is a Python command-line project for running an OpenAI Agents SDK workload inside a hardened, disposable Docker sandbox with a colocated MCP server sidecar.

The project started from the sibling SandboxAgent repository, but changes the topology so the AI agent container is complemented by:

• a Squid proxy container that controls network egress
• an MCP server container that exposes local MCP tools and resources
• a Docker internal network that lets the agent call the MCP sidecar without exposing the sidecar directly to the host

[!WARNING] This is an experimental sandboxing and MCP-sidecar project and should not be treated as a finished security model.

The current workload uses the OpenAI Agents SDK to answer a Microsoft Learn code-sample question. The agent reads a local answer-format resource from the MCP sidecar, calls a Microsoft Learn code-sample search tool through that same sidecar, saves the final answer as answer.txt, and prints the answer to stdout.

Current Workflow

Run the project from the repository root:

.\.venv\Scripts\python.exe -m sandbox_agent

The host-side command loads src/sandbox_agent/sandbox_spec.toml, generates a Dockerfile and low-level Docker profile from that spec, builds or reuses a hash-tagged Docker image for the agent, builds or reuses the MCP sidecar image, creates a per-run Docker network, starts the Squid proxy container, starts the MCP sidecar container, starts a disposable agent container, streams the agent's stdout and stderr to the terminal, persists artifacts, and then removes the disposable containers and network.

Inside the agent container, Sandbox Agent:

1. Creates an OpenAI Agents SDK agent.
2. Reads the MCP resource mcp-sidecar://instructions/answer-format.md.
3. Calls the MCP tool microsoft_code_sample_search with language="csharp".
4. Answers how an instance of HttpClient should be obtained when using C# and .NET 8.
5. Saves the exact answer text to /sandbox-output/answer.txt.
6. Prints the same answer text to stdout.

Run artifacts are written under .docker_sandbox/runs/run-*.

Sandbox Spec

The sandbox is driven by a declarative TOML file:

schema_version = 1
capabilities = [
  "network",
  "mcp_client",
  "openai_agents",
]
allowed_domains = [
  ".example.com",
  ".gov.uk",
  ".microsoft.com"
]
allowed_ip_addresses = []

The design rule is that capabilities soften the sandbox only when necessary. Unknown keys and unsupported capability values fail closed.

allowed_domains and allowed_ip_addresses refine the network capability. They do not enable networking by themselves.

Environment variables can be declared explicitly:

[[environment_variables]]
name = "API_BASE_URL"
value = "https://example.com"

Or copied from the host:

[[environment_variables]]
name = "OPENAI_API_KEY"
from_host = true

OpenAI-backed capabilities add OPENAI_API_KEY automatically where the sandbox system knows the provider convention.

Capabilities

The current workload uses these capabilities:

• network: enables the Squid egress gateway. Network access is default-deny unless domains or IP addresses are allowed by the resolved profile.
• mcp_client: installs the Python MCP client package in the agent image and requires the network capability.
• openai_agents: installs openai-agents, requires network, adds .openai.com, and forwards OPENAI_API_KEY from the host.

The MCP sidecar itself is started by the host-side Docker harness when running the sandbox_agent workload with a network gateway.

MCP Sidecar

The sidecar package can run directly:

.\.venv\Scripts\python.exe -m mcp_sidecar --host 0.0.0.0 --port 8000

By default it uses streamable HTTP on port 8000. The Docker harness starts it on the internal Docker network with the alias mcp-sidecar, and passes this connection string into the agent container:

MCP_SIDECAR_URL=http://mcp-sidecar:8000/mcp

The sidecar currently exposes these MCP tools:

• get_html_element_name: returns a hard-coded HTML element name used by an earlier sample workload.
• microsoft_docs_search: proxies Microsoft Learn documentation search.
• microsoft_docs_fetch: proxies Microsoft Learn documentation fetch.
• microsoft_code_sample_search: proxies Microsoft Learn code sample search.

The sidecar currently exposes this MCP resource:

• mcp-sidecar://instructions/answer-format.md: a Markdown answer format that the agent must read before composing its final answer.

The Microsoft wrapper tools call the public Microsoft Learn MCP endpoint:

https://learn.microsoft.com/api/mcp

When the sidecar is started by the Docker harness, it receives proxy environment variables so its outbound HTTP and HTTPS traffic goes through the Squid gateway:

HTTP_PROXY=http://egress-gateway:3128
HTTPS_PROXY=http://egress-gateway:3128
NO_PROXY=localhost,127.0.0.1,mcp-sidecar

The MCP sidecar Docker image uses python:3.12-slim and installs the mcp package. The host runner bind-mounts src/mcp_sidecar into the sidecar container as read-only source so sidecar Python changes are visible to the next run without rebuilding the image.

Run Artifacts

A successful run directory contains files similar to:

.docker_sandbox/runs/run-YYYY-mm-dd-HH-MM-SS/
  Dockerfile
  answer.txt
  config.json
  gateway-logs.json
  gateway-start-results.json
  landlock-policy.json
  mcp-sidecar-logs.json
  mcp-sidecar-metadata.json
  mcp-sidecar-start-results.json
  mcp-sidecar-stderr.txt
  mcp-sidecar-stdout.txt
  mcp-sidecar-tool-calls.jsonl
  resolved-profile.json
  run-metadata.json
  sandbox-spec.json
  seccomp-profile.json
  squid.conf
  stderr.txt
  stdout.txt

answer.txt contains the final answer saved by the agent. stdout.txt contains the same answer as printed by the in-container process. stderr.txt should normally be empty.

mcp-sidecar-tool-calls.jsonl is the sidecar audit log. It records MCP resource reads and tool calls, including arguments, success or failure, and a short result preview. A successful current run should include a resource record for mcp-sidecar://instructions/answer-format.md and a tool record for microsoft_code_sample_search.

The repository also includes ARCHITECTURE.png, a static infographic showing the current host, Docker network, Squid proxy, MCP sidecar, AI agent container, Microsoft Learn endpoint, and artifact flow.

Sandbox Probes

The project can run the copied SandboxTester probe suite against the generated sandbox:

.\.venv\Scripts\python.exe -m sandbox_agent --test-sandbox

By default, probe evidence is redacted from report.json. To serialize evidence for troubleshooting, run:

.\.venv\Scripts\python.exe -m sandbox_agent --test-sandbox --serialize-evidence

Requirements

• Python 3.11.
• PowerShell on Windows.
• Docker Desktop with Linux containers enabled.
• OPENAI_API_KEY in the host environment for the OpenAI Agents SDK workload.
• Network access during image builds to download Python packages and Docker base images.
• Network access during runs to allowed model-provider and Microsoft Learn endpoints through the Squid gateway.

Docker image builds can take several minutes the first time an image is created.

Setup

Create the virtual environment and install development dependencies:

.\scripts\setup-dev.ps1

The setup script expects Python 3.11 at the path configured in scripts\setup-dev.ps1.

Development Checks

Run formatting, linting, type checking, and tests:

.\scripts\check.ps1

This runs:

• ruff format .
• ruff check .
• pyright
• pytest

Architecture

The project has four main packages:

• sandbox_agent: the in-container workload. It owns the OpenAI Agents SDK prompt, tool adapters, MCP client calls into the sidecar, and answer saving.
• mcp_sidecar: the MCP server container workload. It owns local MCP resources, local MCP tools, Microsoft Learn proxy tools, streamable HTTP server setup, and sidecar audit logging.
• docker_sandbox: the host/container harness copied and adapted from the sibling sandbox projects. It owns sandbox spec loading, Dockerfile generation, profile resolution, image creation, Docker local network creation, Squid gateway setup, MCP sidecar startup, disposable agent container execution, artifact persistence, and teardown.
• sandbox_tester: the copied probe suite used by --test-sandbox to produce report.json for comparing sandbox behavior over time.

The command path deliberately differs by location:

• On the host, python -m sandbox_agent delegates to docker_sandbox.
• Inside the container, python -m sandbox_agent runs the workload.

The in-container path is guarded by SANDBOX_AGENT_CONTAINER=1 and expected mounts such as /sandbox-output, /sandbox-work, and /sandbox-source/src.

The default Docker topology for the current workload is:

Docker host
  docker_sandbox host runner
    |
    +-- Docker internal network
          |
          +-- sandbox-agent-* container
          |     MCP_SIDECAR_URL=http://mcp-sidecar:8000/mcp
          |
          +-- mcp-sidecar-* container
          |     HTTP_PROXY=http://egress-gateway:3128
          |
          +-- squid proxy container
                network alias: egress-gateway

The agent container does not call the Microsoft Learn MCP endpoint directly. It calls the local MCP sidecar, and the sidecar performs the upstream Microsoft Learn MCP call through Squid.

Project Structure

ARCHITECTURE.png               Static Docker topology infographic

src/sandbox_agent/
  __main__.py                  Package entry point for python -m sandbox_agent
  cli.py                       Host delegation and in-container workload entry point
  openai_agent.py              OpenAI Agents SDK workload
  openai_tools.py              OpenAI Agents SDK tool adapters
  sandbox_spec.toml            Declarative sandbox capability spec
  tools.py                     Neutral tools, MCP client calls, and answer saving

src/mcp_sidecar/
  __main__.py                  Package entry point for python -m mcp_sidecar
  audit.py                     JSONL audit logging for resources and tools
  cli.py                       MCP sidecar command-line entry point
  resources.py                 Local MCP resources
  server.py                    FastMCP server construction
  tools.py                     Local and Microsoft Learn proxy tools
  dockerfile/Dockerfile        MCP sidecar image definition

src/docker_sandbox/
  __main__.py                  Package entry point for python -m docker_sandbox
  cli.py                       Docker sandbox command-line orchestration
  container_factory.py         Docker image inspection and build
  container_guard.py           Runtime guard for in-container execution
  landlock_runner.py           Linux Landlock path-policy launcher
  models.py                    Docker orchestration dataclasses
  profiles.py                  Legacy named profile definitions
  run_results.py               Local run artifact persistence
  sandbox_container.py         Containers, network, sidecars, artifacts, teardown
  sandbox_spec.py              Spec validation and profile/Dockerfile generation
  dockerfile/remove_python_packaging.py
  dockerfile/runtime_sitecustomize.py

src/sandbox_tester/
  Probe definitions and report generation used by --test-sandbox

tests/
  test_mcp_sidecar.py
  test_mcp_sidecar_container.py
  test_mcp_sidecar_dockerfile.py
  test_sandbox_agent_tools.py
  test_sandbox_spec.py
  test_sandbox_tester_serialization.py
  test_smoke.py

scripts/
  setup-dev.ps1
  check.ps1

Notes

McpSidecar is a learning and hardening exercise, not a security proof. The container policy reduces accidental host exposure and makes required capability softening visible, but Docker, Landlock, seccomp, Squid, MCP tool boundaries, and Python runtime guards should not be interpreted as a complete isolation guarantee.

Generated content can vary between runs because it is model-generated. Model API calls may incur usage costs.

Run artifacts under .docker_sandbox/runs are ignored by Git.

The Microsoft Learn MCP endpoint is treated as an upstream third-party MCP server. The local sidecar currently proxies selected tools from that endpoint; future versions may add authenticated upstream MCP servers or host-local resources.

Third-Party Notices

This project uses third-party packages including mcp, openai, openai-agents, and pillow. It also uses Docker images such as python:3.12-slim for the MCP sidecar and ubuntu/squid:latest for the Squid gateway. See each package and image license metadata for details.

License

GNU General Public License v3.0. See the LICENSE file for details.