Docker MCP Toolkit: Running Sandboxed AI Agents Securely in Containers

The Model Context Protocol made it easy to give an AI agent hands. A few lines of JSON in a client config and your assistant can read GitHub issues, query a database or drive a browser. The default way to do that is also the risky way: npx some-mcp-server or uvx some-tool, running as your user, on your laptop, with your tokens in plain text in a config file, fetched from a package you did not review.

Containers are an obvious fit for this problem. Each tool server runs in its own isolated process with limited resources, secrets are injected at runtime, and the network is something you can restrict. Docker's MCP Catalog, MCP Toolkit and MCP Gateway package that idea. This post shows how to use them, how to harden a server you write yourself, and how to wire an agent in Compose that sees only the tools you intended.

The risk, stated plainly

An MCP server is code that an agent can call, and an agent follows instructions found in the content it reads. Put those two facts together:

Containers do not solve prompt injection. They limit what any single tool can do once something goes wrong, which is the realistic goal.

The pieces

The important design point: clients talk to one gateway, and the gateway is the only thing that talks to servers. That gives you one place to log, one place to apply policy, and one list of tools to review.

Getting started

# Browse what is available
docker mcp catalog show

# Enable servers
docker mcp server enable github
docker mcp server enable fetch
docker mcp server ls

# Store a secret in Docker's secrets store, not in a config file
docker mcp secret set github.personal_access_token=ghp_xxxxxxxx
docker mcp secret ls

# Connect a client (for example Claude Code or VS Code)
docker mcp client connect vscode
docker mcp client ls

Command names and flags are evolving quickly, so run docker mcp --help and docker mcp gateway run --help on your version rather than trusting a blog post, mine included.

Two habits make this setup safer than it sounds:

• Create a narrow token. A fine-grained GitHub token limited to one repository with read access to issues is a very different asset than a classic token with repo scope. If the secret leaks through an injection, the blast radius is whatever the token can do.
• Enable fewer servers. Every enabled server adds tools to the model's context, which costs tokens and increases the chance it picks the wrong one. Enable what the task needs.

Running the gateway for your own agent

A coding assistant on your laptop is one use. A service you are building is another. Run the gateway as a service in Compose and point the agent at it:

# compose.yaml
services:
  mcp-gateway:
    image: docker/mcp-gateway
    command:
      - --servers=fetch,github
      - --transport=streaming
      - --port=8811
      - --log-calls
    volumes:
      # The gateway starts server containers, so it needs the Docker API
      - /var/run/docker.sock:/var/run/docker.sock
    networks: [agent-net]

  agent:
    build: ./agent
    environment:
      MCP_URL: http://mcp-gateway:8811/mcp
      LLM_BASE_URL: ${LLM_BASE_URL}
      LLM_MODEL: ${LLM_MODEL}
    depends_on: [mcp-gateway]
    networks: [agent-net]
    read_only: true
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]

networks:
  agent-net:
    internal: false

Be honest about the Docker socket mount: giving a container access to docker.sock is effectively root on the host. The gateway needs it to start server containers. That is acceptable on a developer machine or a dedicated build host, and it is a reason not to run this pattern next to anything valuable. In a cluster, replace this with servers deployed as ordinary pods under a restrictive Pod Security level and NetworkPolicy, with a gateway in front.

The agent side

The agent connects with the MCP client library and lists what the gateway exposes. Filter that list before the model ever sees it.

# agent/tools.py
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

ALLOWED = {"fetch", "list_issues", "get_issue"}     # explicit allowlist

async def with_session(fn):
    async with streamablehttp_client(os.environ["MCP_URL"]) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            return await fn(session)

async def list_allowed_tools(session):
    tools = (await session.list_tools()).tools
    return [t for t in tools if t.name in ALLOWED]

async def call_tool(session, name: str, args: dict):
    if name not in ALLOWED:
        raise PermissionError(f"tool {name} is not allowed")
    result = await session.call_tool(name, args)
    return result.content

The allowlist lives in the agent, not only in the gateway. Defence in depth matters here: if the gateway config drifts, the agent still refuses to call create_issue or delete_repo.

Hardening a server you write yourself

Catalog servers are one thing. Most real agents need a custom tool, and the temptation is to write it quickly and run it with full privileges. Here is a small server and the container settings I put around it.

# tools/server.py
from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("orders")
ORDERS_API = "http://orders-api:8080"

@mcp.tool()
async def get_order(order_id: int) -> dict:
    """Fetch one order by numeric id. Read only."""
    if order_id <= 0:
        raise ValueError("order_id must be positive")
    async with httpx.AsyncClient(timeout=5) as client:
        r = await client.get(f"{ORDERS_API}/orders/{order_id}")
        r.raise_for_status()
        order = r.json()
    # Return only what the agent needs; never pass through raw internal records
    return {k: order[k] for k in ("id", "status", "total", "currency", "created_at")}

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=9000)

# tools/Dockerfile
FROM python:3.12-slim AS build
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
COPY --from=build /install /usr/local
WORKDIR /app
COPY server.py .
RUN adduser --disabled-password --uid 10001 tool
USER 10001
EXPOSE 9000
CMD ["python", "server.py"]

  orders-tool:
    build: ./tools
    read_only: true
    tmpfs: ["/tmp"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    mem_limit: 256m
    pids_limit: 100
    cpus: 0.5
    networks: [tool-net]       # can reach orders-api only, not the internet

The tool itself follows the same principles: validate arguments, return the smallest useful result, and prefer many read-only tools over one powerful general tool.

Handling prompt injection realistically

Nothing in this setup makes the model immune to hostile text. Design as if it will sometimes follow it.

The gateway log in the figure above shows the value of the last two: a blocked egress attempt is exactly the kind of event you want to see, and you can only see it if something sits in the path.

What I would check before putting this near real data

• Where do secrets live, who can read them, and how do you rotate them?
• Which servers are enabled, who reviewed them, and are the images pinned by digest?
• What happens if the model calls a tool in a loop? Do you have rate limits and step caps?
• Can the agent reach anything that is not on the allowlist, by any route?
• If this container were fully compromised, what is the worst it could do with the credentials it holds?

Wrap-up

Running MCP servers as containers behind a gateway turns an unreviewed pile of local processes into a small, observable system with one entry point and per-tool limits. The container boundary does not fix prompt injection, but it keeps a bad tool call from becoming a bad day. Start by moving your existing servers behind the gateway and getting tokens out of config files, then harden the tools you write yourself.

Resources

• Docker MCP Catalog and Toolkit documentation
• Docker MCP Gateway on GitHub
• Model Context Protocol specification
• MCP Python SDK
• Docker security best practices
• Docker Compose services reference (read_only, cap_drop, security_opt)
• OWASP Top 10 for LLM Applications