Deploy the MCP Tool Server with Docker Compose: A Complete Guide to Chapter 4 Orchestration

You can deploy the MCP tool server by exporting the required API keys and running docker compose up -d from the chapter4 directory to launch the three isolated services (execution-tools, perception-tools, and collaboration-tools) defined in the docker-compose.yml file.

The MCP (Multi-Component Processing) tool server architecture in the bojieli/ai-agent-book repository demonstrates how to isolate AI agent capabilities into specialized microservices. Using the Docker Compose configuration provided in chapter4/docker-compose.yml, you can orchestrate the entire stack with a single command, ensuring consistent environments across development and production deployments.

Architecture of the MCP Tool Server

The deployment orchestrates three independent containerized services, each responsible for a specific domain of AI agent capabilities.

The Three Core Services

The docker-compose.yml file defines the following services:

• execution-tools: Handles isolated code execution within a secure workspace. Built from chapter4/execution-tools/Dockerfile.
• perception-tools: Manages external data retrieval from sources like arXiv, Yahoo Finance, and Google Search. Built from chapter4/perception-tools/Dockerfile.
• collaboration-tools: Provides file-system operations and browser automation capabilities. Built from chapter4/collaboration-tools/Dockerfile.

Networking and Communication Model

Unlike traditional microservices that expose TCP ports, these MCP servers communicate exclusively via STDIO (standard input/output). The configuration sets stdin_open: true and tty: true for each service, enabling the host controller to pipe JSON commands directly into the containers. All services connect to a dedicated bridge network named mcp-network to facilitate inter-service communication while remaining isolated from the host network.

Prerequisites and Environment Configuration

Before deploying the stack, you must configure the environment variables that the services require to access external APIs.

Required Environment Variables

The docker-compose.yml file uses variable substitution (${VAR_NAME}) to inject secrets at runtime. Export the following keys in your shell:

export OPENAI_API_KEY=sk-your-openai-key
export GOOGLE_API_KEY=your-google-key
export GOOGLE_CSE_ID=your-custom-search-engine-id
export ARXIV_API_KEY=your-arxiv-key
export YAHOO_FINANCE_API_KEY=your-yahoo-key

Security Note: These values are never stored in the YAML file, keeping sensitive credentials out of version control and ensuring they remain ephemeral within the container environment.

Step-by-Step Deployment Guide

Follow these steps to build, launch, and verify the MCP tool server stack.

1. Configure Environment Variables

Set all required API keys in your current shell session as shown in the prerequisites section. You can verify they are set correctly using:

echo $OPENAI_API_KEY

2. Build the Container Images

While docker compose up will build images automatically on first run, you can explicitly build them to cache layers or troubleshoot build issues:

cd chapter4
docker compose build

This command processes the three Dockerfiles located in the service subdirectories (execution-tools, perception-tools, and collaboration-tools).

3. Launch the MCP Stack

Start all three services in detached mode:

docker compose up -d

Docker Compose performs the following actions:

• Creates the mcp-network bridge network.
• Provisions three named volumes (execution-workspace, perception-data, collaboration-workspace) for persistent storage.
• Builds and starts containers for each service with STDIO access enabled.

4. Verify Service Health

Check that all containers are running and healthy:

docker compose ps

Inspect the logs for a specific service to confirm successful initialization:

docker compose logs execution-tools

5. Interact with MCP Servers

Since the services expose no network ports, you interact with them by piping JSON commands through Docker's exec interface:

echo '{"cmd":"run","code":"print(2+2)"}' | \
docker exec -i mcp-execution-tools python -u /app/agent.py

This command sends a code execution request to the execution-tools container and returns the result via stdout.

6. Teardown and Cleanup

To stop and remove the containers while preserving data volumes:

docker compose down

To remove the containers and delete all persistent volumes (wiping workspace data):

docker compose down --volumes

Key Configuration Details in docker-compose.yml

The orchestration relies on several critical Docker Compose features defined in the source file.

Build Contexts and Dockerfiles

Each service specifies a build context pointing to its respective subdirectory. For example, the execution-tools service uses:

build:
  context: ./execution-tools

This ensures Docker builds the image using the Dockerfile contained within that directory, locking down the Python runtime and dependencies.

Persistent Storage Volumes

The configuration mounts named volumes to preserve data across container restarts:

• execution-workspace mapped to /workspace in the execution-tools container.
• perception-data mapped to /data in the perception-tools container.
• collaboration-workspace mapped to /workspace in the collaboration-tools container.

These volumes are declared in the volumes section of the compose file and created automatically on first run.

Health Checks and Restart Policies

Each service includes health check definitions to ensure Docker can detect unhealthy states. While the specific check command varies by service, they typically verify that the Python environment is responsive. Combined with restart policies, this ensures high availability of the tool server components.

Summary

Deploying the MCP tool server using Docker Compose provides a reproducible, isolated environment for AI agent capabilities. Key takeaways include:

• Three specialized services (execution, perception, collaboration) run in separate containers built from individual Dockerfiles.
• STDIO-based communication eliminates network port exposure while allowing direct JSON command piping.
• Named volumes persist workspace data and downloaded resources across container lifecycles.
• Environment variable injection keeps API secrets secure and out of the repository.
• Single-command deployment via docker compose up -d orchestrates the entire stack defined in chapter4/docker-compose.yml.

Frequently Asked Questions

What is the MCP tool server architecture used for?

The MCP (Multi-Component Processing) tool server architecture isolates different AI agent capabilities into dedicated microservices to improve security and resource management. According to the bojieli/ai-agent-book source code, this separation allows the execution of untrusted code, retrieval of external data, and file-system operations to run in sandboxed containers with limited privileges.

Why do the MCP services use STDIO instead of HTTP ports?

The services use standard input/output streams (stdin_open: true and tty: true in the docker-compose.yml) to communicate because the MCP protocol is designed for process-based tool invocation. This design eliminates the need for network port mapping, reduces the attack surface by avoiding exposed TCP endpoints, and allows the host controller to manage tool execution through simple pipe operations rather than HTTP requests.

How do I add new environment variables for additional API keys?

To add new secrets, first export them in your shell (export NEW_API_KEY=value), then reference them in the environment section of the docker-compose.yml file using the ${NEW_API_KEY} syntax. Ensure you do not commit the actual values to version control; only the variable names should appear in the compose file.

Can I scale individual MCP services independently?

Yes. Because each service is defined as a separate container with its own build context and volume, you can scale them independently using Docker Compose commands. For example, docker compose up --scale perception-tools=3 would create three instances of the perception service, though you would need to ensure your controller logic can distribute requests across these instances since they communicate via STDIO rather than a load-balanced network port.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}