Skip to main content
This page documents the integration layers provided by the Palyra CLI to facilitate communication between external agents (IDEs, LLM-based tools) and the Palyra Core Daemon. It covers the stateful Agent Control Protocol (ACP) bridge, the Model Context Protocol (MCP) facade, and the CLI-v1 compatibility shims.

​
Overview

Palyra provides two primary protocols for programmatic interaction:
  1. ACP (Agent Control Protocol): A stateful, session-aware bridge designed for IDE-native integrations where long-lived session lifecycle and inline permission prompts are required [crates/palyra-cli/data/docs/cli-v1-acp-shim.md#52-53](http://crates/palyra-cli/data/docs/cli-v1-acp-shim.md#52-53).
  2. MCP (Model Context Protocol): A stateless stdio facade following the Model Context Protocol specification, optimized for tool-driven clients that expect tools/list and tools/call patterns [crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#39-39](http://crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#39-39).

​
System Data Flow: ACP & MCP Interop

The following diagram illustrates how the CLI components bridge external protocol requests to the internal gRPC services of the daemon. Diagram: Protocol Bridge Architecture Sources: [crates/palyra-cli/src/acp_bridge.rs#7-18](http://crates/palyra-cli/src/acp_bridge.rs#7-18), [crates/palyra-cli/src/commands/mcp.rs#46-54](http://crates/palyra-cli/src/commands/mcp.rs#46-54), [crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#32-34](http://crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#32-34)

​
Agent Control Protocol (ACP) Bridge

The ACP bridge, implemented in acp_bridge.rs, allows the Palyra CLI to act as an ACP server. It translates ACP session notifications and permission requests into Palyra gRPC gateway calls.

​
Bridge State & Session Binding

The BridgeState struct manages the mapping between ACP’s view of sessions and Palyra’s internal ULIDs. It tracks:
  • bindings_by_acp_session_id: Maps the client-provided ID to a SessionBinding [crates/palyra-cli/src/acp_bridge.rs#48-48](http://crates/palyra-cli/src/acp_bridge.rs#48-48).
  • bindings_by_session_key: Maps stable session keys to active bindings [crates/palyra-cli/src/acp_bridge.rs#49-49](http://crates/palyra-cli/src/acp_bridge.rs#49-49).
  • active_runs: Tracks current execution IDs associated with ACP sessions [crates/palyra-cli/src/acp_bridge.rs#43-43](http://crates/palyra-cli/src/acp_bridge.rs#43-43).

​
Implementation Details

The PalyraAcpAgent struct implements the core logic for handling ACP requests. It utilizes an asynchronous runtime to manage gRPC streams.
FunctionDescription
send_session_updateDispatches SessionNotification to the client via mpsc channel [crates/palyra-cli/src/acp_bridge.rs#134-146](http://crates/palyra-cli/src/acp_bridge.rs#134-146).
request_permissionTriggers a permission request to the ACP client, returning a RequestPermissionResponse [crates/palyra-cli/src/acp_bridge.rs#152-165](http://crates/palyra-cli/src/acp_bridge.rs#152-165).
read_meta_stringUtility to extract metadata overrides (like sessionKey) from ACP _meta objects [crates/palyra-cli/src/acp_bridge.rs#167-182](http://crates/palyra-cli/src/acp_bridge.rs#167-182).
Sources: [crates/palyra-cli/src/acp_bridge.rs#39-44](http://crates/palyra-cli/src/acp_bridge.rs#39-44), [crates/palyra-cli/src/acp_bridge.rs#115-132](http://crates/palyra-cli/src/acp_bridge.rs#115-132)

​
Model Context Protocol (MCP) Facade

The MCP facade provides a standard stdio server interface for LLM tool-calling. It is invoked via palyra mcp serve [crates/palyra-cli/src/commands/mcp.rs#24-25](http://crates/palyra-cli/src/commands/mcp.rs#24-25).

​
Tool Surface

The MCP implementation exposes a subset of Palyra’s capabilities as discrete tools.
Tool NameTypePurpose
sessions_listReadLists available chat sessions with filtering [crates/palyra-cli/src/commands/mcp.rs#115-135](http://crates/palyra-cli/src/commands/mcp.rs#115-135).
session_transcript_readReadFetches the full JSON transcript of a session [crates/palyra-cli/src/commands/mcp.rs#137-156](http://crates/palyra-cli/src/commands/mcp.rs#137-156).
memory_searchReadExecutes vector/FTS search across the agent’s memory [crates/palyra-cli/src/commands/mcp.rs#17-17](http://crates/palyra-cli/src/commands/mcp.rs#17-17).
session_promptMutationSends a prompt to an agent; handles approval_required status [crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#32-34](http://crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#32-34).
approval_decideMutationResolves a pending human-in-the-loop approval [crates/palyra-cli/src/commands/mcp.rs#20-20](http://crates/palyra-cli/src/commands/mcp.rs#20-20).

​
LiveMcpBackend

The LiveMcpBackend struct is responsible for executing these tools by calling the OperatorRuntime or interacting with the Admin API over HTTP [crates/palyra-cli/src/commands/mcp.rs#111-113](http://crates/palyra-cli/src/commands/mcp.rs#111-113). Diagram: MCP Tool Execution Flow Sources: [crates/palyra-cli/src/commands/mcp.rs#115-156](http://crates/palyra-cli/src/commands/mcp.rs#115-156), [crates/palyra-cli/src/commands/mcp.rs#80-88](http://crates/palyra-cli/src/commands/mcp.rs#80-88)

​
CLI-v1 ACP Shim & Compatibility

The CLI maintains a set of compatibility shims to ensure that existing automation and IDE plugins continue to function as the protocol evolves.

​
Security Posture

Both ACP and MCP bridges strictly adhere to the daemon’s security policies:
  • Read-Only Mode: The MCP server can be started with --read-only to disable mutation tools [crates/palyra-cli/src/args/mcp.rs#13-14](http://crates/palyra-cli/src/args/mcp.rs#13-14).
  • Sensitive Tools: Explicit flags like --allow-sensitive-tools are required to enable tools that can trigger significant actions or approvals [crates/palyra-cli/src/args/mcp.rs#15-16](http://crates/palyra-cli/src/args/mcp.rs#15-16).
  • Auth Parity: Bridges use the same profile-based token and principal resolution as the standard CLI commands [crates/palyra-cli/src/commands/mcp.rs#38-49](http://crates/palyra-cli/src/commands/mcp.rs#38-49).

​
Command Aliases

The CLI-v1 shim maintains several legacy aliases for common operations:
  • init → setup [crates/palyra-cli/data/docs/cli-v1-acp-shim.md#35-36](http://crates/palyra-cli/data/docs/cli-v1-acp-shim.md#35-36).
  • daemon → gateway [crates/palyra-cli/data/docs/cli-v1-acp-shim.md#35-36](http://crates/palyra-cli/data/docs/cli-v1-acp-shim.md#35-36).
  • onboard → onboarding wizard [crates/palyra-cli/data/docs/cli-v1-acp-shim.md#35-36](http://crates/palyra-cli/data/docs/cli-v1-acp-shim.md#35-36).

​
Diagnostic Commands

To troubleshoot bridge connectivity, the CLI provides:
  • palyra gateway discover --verify-remote --json: Reports trust state and handshake status [crates/palyra-cli/src/commands/daemon.rs#48-50](http://crates/palyra-cli/src/commands/daemon.rs#48-50).
  • palyra support-bundle export: Generates a diagnostic archive including ACP/MCP interop logs [crates/palyra-cli/data/docs/cli-v1-acp-shim.md#66-67](http://crates/palyra-cli/data/docs/cli-v1-acp-shim.md#66-67).
Sources: [crates/palyra-cli/data/docs/cli-v1-acp-shim.md#1-85](http://crates/palyra-cli/data/docs/cli-v1-acp-shim.md#1-85), [crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#1-85](http://crates/palyra-cli/data/docs/cli-mcp-interop-playbook.md#1-85)