Crate sacp_proxy 

sacp-proxy

Framework for building ACP proxy components that extend agent functionality.

What are proxies?

Proxies are modular components that sit between an editor and an agent, intercepting and transforming messages. They enable composable agent architectures where functionality can be added without modifying the base agent.

Editor → Proxy 1 → Proxy 2 → Agent

Use cases:

• Add MCP tools/resources/prompts to any agent
• Inject context or modify prompts before they reach the agent
• Filter or transform agent responses
• Add logging, metrics, or policy enforcement

Quick Start

The simplest proxy just forwards messages unchanged:

use sacp::JrHandlerChain;
use sacp_proxy::{AcpProxyExt, McpServiceRegistry};
use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};

JrHandlerChain::new()
    .name("my-proxy")
    .provide_mcp(McpServiceRegistry::default())  // Provide MCP services
    .proxy()  // Enable proxy mode
    .serve(sacp::ByteStreams::new(
        tokio::io::stdout().compat_write(),
        tokio::io::stdin().compat()
    ))
    .await?;

To add MCP tools to the proxy, provide an MCP server:

use sacp::JrHandlerChain;
use sacp_proxy::{AcpProxyExt, McpServiceRegistry};
use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};

JrHandlerChain::new()
    .name("my-proxy")
    // Add MCP servers to provide tools/resources/prompts
    .provide_mcp(
        McpServiceRegistry::default()
            // .with_rmcp_server("my-server", || MyMcpServer::new())?
    )
    .proxy()
    .serve(sacp::ByteStreams::new(
        tokio::io::stdout().compat_write(),
        tokio::io::stdin().compat()
    ))
    .await?;

See the with_mcp_server.rs example for a complete implementation.

Key Concepts

Predecessor vs Successor:

• Predecessor - The component closer to the editor (could be editor or another proxy)
• Successor - The component farther from the editor (could be agent or another proxy)

Messages flow: Predecessor → This Proxy → Successor

Extension Traits:

• AcpProxyExt - Adds proxy-specific methods to JrConnection
• JrCxExt - Adds forwarding methods (send_to_predecessor, send_to_successor)

Examples

See the examples directory:

• minimal.rs - Simplest possible proxy that forwards everything unchanged
• with_mcp_server.rs - Proxy that adds MCP tools to any agent

How Proxies Work

When you call .proxy(), the framework:

1. Handles capability negotiation with predecessor and successor
2. Sets up message routing between components
3. Wraps your handlers to intercept specific message types
4. Forwards everything else automatically

You only need to handle the messages you want to intercept or transform.

Related Crates

• sacp - Core ACP SDK
• sacp-conductor - Binary for orchestrating proxy chains
• sacp-tokio - Tokio utilities for spawning agents

Structs

McpConnectRequest

Creates a new MCP connection. This is equivalent to “running the command”.

McpConnectResponse

Response to an MCP connect request

McpDisconnectNotification

Disconnects the MCP connection.

McpOverAcpNotification

An MCP notification sent via ACP, either from the MCP client (the ACP agent) or the MCP server (the ACP client).

McpOverAcpRequest

An MCP request sent via ACP. This could be an MCP-server-to-MCP-client request (in which case it goes from the ACP client to the ACP agent, note the reversal of roles) or an MCP-client-to-MCP-server request (in which case it goes from the ACP agent to the ACP client).

McpServiceRegistry

Manages MCP services offered to successor proxies and agents.

MessageFromSuccessorHandler

Handler to process a message of type R coming from the successor component.

NotificationFromSuccessorHandler

Handler to process a notification of type N coming from the successor component.

ProxyHandler

Handler for the “default proxy” behavior.

RequestFromSuccessorHandler

Handler to process a request of type R coming from the successor component.

SuccessorNotification

A notification being sent to the successor component.

SuccessorRequest

A request being sent to the successor component.

Constants

METHOD_MCP_CONNECT_REQUEST

JSON-RPC method name for MCP connect requests

METHOD_MCP_DISCONNECT_NOTIFICATION

JSON-RPC method name for MCP disconnect notifications

METHOD_MCP_NOTIFICATION

JSON-RPC method name for MCP notifications over ACP

METHOD_MCP_REQUEST

JSON-RPC method name for MCP requests over ACP

Traits

AcpProxyExt

Extension trait for JrConnection that adds proxy-specific functionality

JrCxExt

Extension trait for JrConnectionCx that adds methods for sending to successor.