High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• src/container_use_mcp.rs
• extension.toml
• README.md
• Cargo.toml
• configuration/installation_instructions.md

The Container Use MCP extension for Zed provides an integration layer between the Zed editor and the Container Use Model Context Protocol (MCP) server. Its primary purpose is to enable coding agents within Zed to operate within containerized environments, ensuring isolated and reproducible development spaces. The architecture facilitates the discovery, configuration, and execution of the cu (Container Use) binary as a context server.

Sources: README.md:1-5, extension.toml:1-4

Core Components

The architecture consists of a Rust-based extension that implements the Zed Extension API to manage the lifecycle and communication with the external cu process.

ContainerUseMcpExtension

This is the primary state container for the extension. It manages the caching of the MCP server binary path to avoid redundant lookups.

• cached_binary_path: An optional String storing the resolved path to the cu binary.

Sources: src/container_use_mcp.rs:16-18

Configuration & Settings

The extension supports both automatic discovery of the cu binary and manual configuration via Zed's settings.

Setting	Type	Description
cu_path	Option<String>	Explicit path to the cu binary.

Sources: src/container_use_mcp.rs:10-14, README.md:15-26

Process & Execution Flow

The extension follows a structured flow to initialize the context server, beginning with binary discovery and ending with the execution of a stdio-based command.

Binary Resolution Logic

The extension attempts to locate the cu binary using the following priority:

1. Custom Path: Checks if a path is provided in settings.json.
2. System PATH: Executes the which cu command to find the binary in the system environment.
3. Cache: Utilizes the cached_binary_path if previously resolved.

Sources: src/container_use_mcp.rs:24-51, extension.toml:11-14

The following diagram illustrates the binary discovery and server startup sequence:

MCP Server Lifecycle

The extension implements zed::Extension traits to interface with Zed's extension host.

Function	Purpose
context_server_command	Constructs the Command to start the cu server with stdio arguments.
context_server_configuration	Provides the schema, default settings, and installation instructions to Zed.
context_server_binary_path	Internal helper to resolve the cu executable location.

Sources: src/container_use_mcp.rs:54-106

Data Flow: Editor to Container

The extension facilitates communication between Zed's AI agents and the containerized environment via the MCP protocol.

Integration Requirements

For the architecture to function correctly, specific external components must be present:

• The cu Binary: Must be installed and available in the system PATH or configured via settings.
• Agent Rules: A .rules file derived from the Container Use repository should be present in the project root to guide agent behavior.
• Zed Extension API: The extension relies on zed_extension_api version 0.5.0.

Sources: configuration/installation_instructions.md:1-2, Cargo.toml:13, README.md:8-13

Summary

The High-Level Architecture of the Container Use MCP extension is a lightweight bridge. It leverages Rust and the Zed Extension API to dynamically locate and launch the cu binary. By managing the process lifecycle and configuration schema, it allows Zed to seamlessly delegate task execution to containerized environments through the standard MCP stdio interface.