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

> Easily deploy the MCP tool server using Docker Compose. Follow this guide to launch execution, perception, and collaboration tools with a single command.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-08-23

---

**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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/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](https://github.com/bojieli/ai-agent-book/blob/main/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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/docker-compose.yml) file defines the following services:

- **execution-tools**: Handles isolated code execution within a secure workspace. Built from [chapter4/execution-tools/Dockerfile](https://github.com/bojieli/ai-agent-book/blob/main/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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/perception-tools/Dockerfile).
- **collaboration-tools**: Provides file-system operations and browser automation capabilities. Built from [chapter4/collaboration-tools/Dockerfile](https://github.com/bojieli/ai-agent-book/blob/main/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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/docker-compose.yml) file uses variable substitution (`${VAR_NAME}`) to inject secrets at runtime. Export the following keys in your shell:

```bash
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:

```bash
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:

```bash
cd chapter4
docker compose build

```

This command processes the three Dockerfiles located in the service subdirectories ([execution-tools](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/execution-tools/Dockerfile), [perception-tools](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/perception-tools/Dockerfile), and [collaboration-tools](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/collaboration-tools/Dockerfile)).

### 3. Launch the MCP Stack

Start all three services in detached mode:

```bash
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:

```bash
docker compose ps

```

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

```bash
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:

```bash
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:

```bash
docker compose down

```

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

```bash
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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/docker-compose.yml).

### Build Contexts and Dockerfiles

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

```yaml
build:
  context: ./execution-tools

```

This ensures Docker builds the image using the [Dockerfile](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/execution-tools/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](https://github.com/bojieli/ai-agent-book/blob/main/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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/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](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/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.