Intro + Architecture

Author: ConradIrwin

docs/images/mcp-proxy.d2

@@ -0,0 +1,34 @@
+'Code Editor': {near: top-center}
+
+'MCP Proxy': {near: center-left}
+# 'MCP Server ...': {
+#   near: center-right
+#   style: {
+#     stroke-dash: 3
+#   }
+# }
+" ---------------------------------------------- ": {
+  style: {
+    fill: transparent
+    font-color: transparent
+    stroke-width: 0
+  }
+}
+
+# Bottom row: Agent
+Agent: {near: bottom-center}
+
+# Connections
+'Code Editor' -> Agent: MCP Proxy Configuration {
+  style: {
+    stroke-dash: 3
+  }
+}
+
+# The agent connects up to the MCP servers
+Agent <-> 'MCP Proxy': MCP over stdio {direction: up}
+'MCP Proxy' <-> 'Code Editor': MCP over socket {
+  style: {
+    stroke-dash: 3
+  }
+}

docs/images/mcp-proxy.svg

@@ -0,0 +1,30 @@
+'Code Editor': {near: top-center}
+
+'MCP Server 1': {near: center-left}
+'MCP Server ...': {
+  near: center-right
+  style: {
+    stroke-dash: 3
+  }
+}
+" ----------------------- ": {
+  style: {
+    fill: transparent
+    font-color: transparent
+    stroke-width: 0
+  }
+}
+
+# Bottom row: Agent
+Agent: {near: bottom-center}
+
+# Connections
+'Code Editor' -> Agent: MCP Configuration {direction: down}
+
+# The agent connects up to the MCP servers
+Agent -> 'MCP Server 1': MCP {direction: up}
+Agent -> 'MCP Server ...': MCP {
+  style: {
+    stroke-dash: 3
+  }
+}

docs/images/mcp.d2

@@ -0,0 +1,17 @@
+# file generated by putting this code into https://play.d2lang.com/
+# and setting theme to Earth tones
+Code Editor -> agent1: stdio
+agent1: Agent 1
+Code Editor -> agent2: stdio
+agent2: Agent 2
+
+Code Editor -> "...": {
+  style: {
+    stroke-dash: 3
+  }
+}
+"...": {
+  style: {
+    stroke-dash: 3
+  }
+}

docs/images/mcp.svg

@@ -5,214 +5,30 @@ description: "Overview of the Agent Client Protocol architecture"
 
 The Agent Client Protocol defines a standard interface for communication between AI agents and client applications. The architecture is designed to be flexible, extensible, and platform-agnostic.
 
-![Agent Client Protocol Architecture](/images/architecture-diagram.png)
-
 ## Design Philosophy
 
 The protocol architecture follows several key principles:
 
-### 1. **Session-Based Isolation**
-Each interaction operates within a session context, providing:
-- State isolation between different conversations
-- Clean lifecycle management
-- Resource scoping and cleanup
-
-### 2. **Tool-Centric Design**
-The protocol treats all operations as tools, creating a uniform interface for:
-- MCP server integrations (`McpToolId`)
-- Client-provided capabilities (`ClientTools`)
-- Permission-gated operations
-
-### 3. **Streaming-First Communication**
-Built for real-time interaction through:
-- Chunked message delivery (`agentMessageChunk`, `agentThoughtChunk`)
-- Progressive tool execution updates (`toolCallUpdate`)
-- Incremental plan revelations
-
-## Component Architecture
-
-### Component Boundaries
-
-1. **Client Application Layer**
-   - Manages UI/UX concerns
-   - Handles permission dialogs
-   - Provides file system access through controlled tools
-
-2. **ACP Protocol Layer**
-   - Session lifecycle management
-   - Message routing and transformation
-   - Tool orchestration
-   - Permission enforcement
-
-3. **Agent Layer**
-   - LLM integration
-   - Reasoning and planning
-   - Tool selection and execution
-   - Response generation
-
-## Key Architectural Patterns
-
-### 1. Tool Abstraction Pattern
-
-All capabilities are exposed as tools with a consistent interface:
-
-```rust
-pub struct McpToolId {
-    pub mcp_server: String,
-    pub tool_name: String,
-}
-```
-
-This abstraction enables:
-- Uniform permission handling
-- Consistent execution tracking
-- Flexible capability composition
-
-### 2. Content Polymorphism
-
-The protocol uses discriminated unions for content flexibility:
-
-```rust
-pub enum ContentBlock {
-    Text(TextContent),
-    Image(ImageContent),
-    Audio(AudioContent),
-    ResourceLink(ResourceLink),
-    // ... extensible
-}
-```
-
-Benefits:
-- Type-safe content handling
-- Forward compatibility
-- Rich media support
-
-### 3. Update Streaming Pattern
-
-Session updates follow a streaming pattern for responsive interaction:
-
-```rust
-pub enum SessionUpdate {
-    Started,
-    UserMessage(ContentBlock),
-    AgentMessageChunk(ContentBlock),
-    AgentThoughtChunk(ContentBlock),
-    ToolCall(ToolCall),
-    ToolCallUpdate(ToolCallUpdate),
-    Plan(Plan),
-}
-```
-
-This enables:
-- Real-time feedback
-- Progressive rendering
-- Interruptible operations
-
-## Implementation Considerations
-
-### State Management
-
-The protocol maintains minimal shared state:
-- **Session State**: Managed by session ID, includes configuration and context
-- **Tool State**: Tracked through tool call IDs for update correlation
-- **Permission State**: Cached permission decisions (allow/reject always)
-
-### Error Boundaries
-
-Error handling is localized to maintain system stability:
-- Tool failures don't crash sessions
-- MCP server errors are isolated
-- Network failures are recoverable
-
-### Performance Optimization
-
-Key areas for optimization:
-1. **Streaming Buffers**: Chunk size tuning for message streams
-2. **Tool Parallelization**: Concurrent tool execution where safe
-3. **Session Caching**: Reuse of MCP server connections
-4. **Content Deduplication**: Efficient handling of repeated resources
-
-## Integration Patterns
-
-### 1. MCP Server Integration
-
-```rust
-pub struct McpServerConfig {
-    pub command: PathBuf,
-    pub args: Vec<String>,
-    pub env: Option<HashMap<String, String>>,
-    pub enabled_tools: Option<Vec<String>>,
-}
-```
-
-Supports:
-- Dynamic server spawning
-- Tool whitelisting
-- Environment isolation
-
-### 2. Client Tool Mapping
-
-```rust
-pub struct ClientTools {
-    pub request_permission: Option<McpToolId>,
-    pub write_text_file: Option<McpToolId>,
-    pub read_text_file: Option<McpToolId>,
-}
-```
-
-Enables:
-- Flexible tool implementation
-- Platform-specific capabilities
-- Security boundaries
-
-### 3. Permission Flow
-
-The architecture enforces a clear permission flow:
-1. Agent requests operation
-2. Protocol checks permission cache
-3. If needed, client prompts user
-4. Decision cached based on kind (`allowAlways`, etc.)
-5. Operation proceeds or fails
-
-## Extensibility Points
-
-The architecture provides several extension mechanisms:
+1. **MCP-based**: The protocol is built on JSON-RPC, and re-uses MCP types where possible so that integrators don't need to build yet-another representation for common data types.
+2. **UX-first**: It is designed to solve the UX challenges of interacting with AI agents; ensuring there's enough flexibility to render clearly the agents intent, but is no more abstract than it needs to be.
+3. **Trusted**: ACP works when you're using a code editor to talk to a model you trust. You still have controls over the agent's tool calls, but the code editor gives the agent access to local files and MCP servers.
 
-### 1. Custom Content Types
-New `ContentBlock` variants can be added without breaking existing clients
+## Setup
 
-### 2. Tool Categories
-The `ToolKind` enum can be extended for new operation types
+When the user tries to connect to an agent, the editor boots the agent sub-process on demand, and all communication happens over stdin/stdout.
 
-### 3. Session Updates
-New `SessionUpdate` variants enable protocol evolution
+Each connection can suppport several concurrent sessions, so you can have multiple trains of thought going on at once.
 
-### 4. Annotations
-The `Annotations` type allows metadata extension without schema changes
+![Server Client setup](./images/server-client.svg)
 
-## Security Architecture
+ACP makes heavy use of JSON-RPC notifications to allow the agent to stream updates to the UI in real-time. It also uses JSON-RPC's bidrectional requests to allow the agent to make requests of the code editor: for example to request permissions for a tool call.
 
-### Principle of Least Privilege
-- Tools are explicitly granted through `enabled_tools`
-- File operations require specific client tool mappings
-- Permissions are granular and auditable
+## MCP
 
-### Isolation Boundaries
-- Sessions cannot interact with each other
-- MCP servers run in separate processes
-- File access is mediated through client tools
+Commonly the code editor will have user-configured MCP servers. When forwarding the prompt from the user, it passes configuration for these to the agent. This allows the agent to connect directly to the MCP server.
 
-### Trust Model
-```
-Client (Trusted) ← ACP Protocol → Agent (Sandboxed)
-                        ↓
-                  MCP Servers (Isolated)
-```
+![MCP Server connection](./images/mcp.svg)
 
-## Future Considerations
+The code editor may itself also wish to export MCP based tools. Instead of trying to run MCP and ACP on the same socket, the code editor can provide its own MCP server as configuration. As agents may only support MCP over stdio, the code editor can provide a small proxy that tunnels requests back to itself:
 
-The architecture is designed to accommodate:
-- **Multiplexed Sessions**: Multiple agents in one session
-- **Bidirectional Tools**: Client-initiated tool calls
-- **Resource Streaming**: Large file handling without full loading
-- **Federated Permissions**: Cross-session permission sharing
+![MCP connection to self](./images/mcp-proxy.svg)

docs/images/server-client.d2

@@ -3,9 +3,9 @@ title: "Introduction"
 description: "Get started with the Agent Client Protocol (ACP)"
 ---
 
-The Agent Client Protocol (ACP) is a protocol that standardizes communication between code editors (interactive programs for viewing and editing source code) and coding agents (programs that use generative AI to autonomously modify code).
+The Agent Client Protocol standardizes communication between code editors (IDEs, text-editors, etc.) and coding agents (programs that use generative AI to autonomously modify code).
 
-The protocol is still under heavy development, and we aim to standardize it as we get confidence in the design by implementing it in various settings.
+The protocol is still under development, but it should be complete enough to build interesting user experiences using it.
 
 ## Why ACP?
 
@@ -21,22 +21,26 @@ This decoupling allows both sides to innovate independently while giving develop
 
 ## Overview
 
-The protocol is newline-delimited JSON sent over stdin/stdout. When a code editor wants to start a session with an agent, it boots it as a sub-process (inheriting any environment variables) and sends an initialize request to get the state of the world.
+ACP assumes that the user is primarily in their editor, and wants to reach out and use agents to assist them with specific tasks.
 
-If authentication is required, it can send authenticate to allow the agent to perform any authentication actions (like an Oauth flow).
+Agents run as sub-processes of the code editor, and communicate using JSON-RPC over stdio. The protocol re-uses the JSON representations used in MCP where possible, but includes custom types for things like Diffs that are useful for agentic coding.
 
-Once the agent is ready, the client can send sendUserMessage requests with content from the user. The agent sends streamAssistantMessageChunk and related tool call messages to update the UI while handling the user's message, and finally responds when there will be no more output.
+The default format for user-readable text is Markdown, which allows enough flexibility to represent rich formatting without requiring that the code editor is capable of rendering HTML.
 
-## Architecture
+## Implementations
 
-ACP follows a simple client-server architecture where the client (typically a code editor or IDE) spawns the agent as a subprocess and communicates via standard input/output streams. The protocol uses newline-delimited JSON-RPC 2.0 messages, ensuring compatibility with existing tooling and easy debugging. The client maintains control over the agent's lifecycle and can manage multiple concurrent sessions. Each session represents an isolated conversation context where the agent can access editor-provided tools for reading files, writing changes, and requesting user permissions for sensitive operations.
+Currently ACP is supported by:
 
-```
-┌─────────────────┐                    ┌─────────────────┐
-│                 │                    │                 │
-│     Client      │    stdin/stdout    │      Agent      │
-│      (IDE)      │ ←────────────────→ │    (AI Tool)    │
-│                 │    JSON-RPC 2.0    │                 │
-│                 │                    │                 │
-└─────────────────┘                    └─────────────────┘
-```
+### Editors
+
+- [Zed](https://zed.dev)
+- [neovim](https://neovim.io) if you install the [CodeCompanion](https://codecompanion.olimorris.dev) plugin.
+
+### Agents
+
+- [Gemini](https://github.com/google-gemini/gemini-cli)
+- ... more coming soon ;)
+
+## Further reading
+
+For an overview of the architecture, see the [Architecture](./Architecture) section. For ... TODO