MCP Transport Layer
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Transport Layer is a critical component of the Memory Context Browser (MCB) that facilitates communication between AI coding agents and the MCB server using the Model Context Protocol (MCP). It abstracts the underlying communication mechanisms, allowing for multiple interaction modes such as standard I/O (stdio) for local CLI agents and HTTP/SSE for remote or web-based integrations.
This layer is responsible for serializing and deserializing JSON-RPC messages, managing session lifecycles, and enforcing provenance and security gates. By following Clean Architecture principles, the transport layer acts as a gateway that translates protocol-specific requests into domain-level actions.
Sources: crates/mcb-server/Cargo.toml, README.md:1-15, AGENTS.md:150-165
Architecture and Components
The transport layer is primarily housed within the mcb-server crate, which handles the MCP protocol, Axum HTTP server, and various transport implementations. It relies on the rmcp SDK to provide the core protocol structures and types.
Layered Structure
Communication flows through a defined hierarchy where the transport layer sits at the outermost boundary:
- Transport Implementation: (Stdio, HTTP/SSE) Receives raw bytes.
- Protocol Parser: Deserializes JSON-RPC 2.0 requests.
- Tool Router: Maps method names (e.g.,
tools/call) to specific handlers. - Domain Port: Invokes business logic via the
mcb-domaininterfaces.
Sources: crates/mcb-server/Cargo.toml:40-60, AGENTS.md:168-185
Component Relationship Diagram
The following diagram illustrates how transport components interact with the rest of the MCB workspace.
Sources: README.md:58-75, AGENTS.md:168-185
Supported Transport Protocols
MCB supports multiple transport modes to accommodate different deployment scenarios. The protocol version used is 2024-11-05.
Stdio Transport
Used primarily for local agent integration (e.g., Claude Desktop). The agent spawns the mcb binary and communicates via stdin and stdout. This is the most common execution flow for CLI-based AI tools.
HTTP and SSE Transport
For remote connections, MCB utilizes an Axum-based HTTP server. It supports Server-Sent Events (SSE) for streaming responses, which is essential for long-running tasks like repository indexing.
| Feature | Stdio | HTTP/SSE |
|---|---|---|
| Primary Use | Local CLI Agents | Remote/Web Clients |
| Streaming | Synchronous/Framed | Native SSE |
| Authentication | Process-based | API Key / Headers |
| Configuration | --stdio flag | loco YAML config |
Sources: README.md:38-50, crates/mcb-server/Cargo.toml:68-85, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:30-40
Execution Flows and Provenance
The transport layer enforces strict "Operation Mode Matrix" rules and provenance checks to ensure data integrity and security.
Execution Flow Matrix
The system distinguishes between different execution environments using the HTTP_HEADER_EXECUTION_FLOW header.
stdio-only: Pure local execution.server-hybrid: Server-side processing with remote connectivity.hybrid: Shared execution between client and server.
Certain tools are blocked depending on the flow. For example, validate_code is blocked in server-hybrid flow to prevent unauthorized architecture analysis.
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:27-35, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:134-148
Provenance Gating
Data plane tools (like index_repo or search_code) require a ToolExecutionContext populated with provenance data. Requests lacking these fields are rejected with error code -32602.
Data Structures and Protocol
The transport layer uses standard JSON-RPC 2.0 structures defined in the mcb-domain and rmcp crates.
MCP Request Structure
A standard request must include the jsonrpc version, an id, and a method.
| Field | Type | Description |
|---|---|---|
jsonrpc | String | Must be "2.0" |
id | Value | Request identifier (Integer or String) |
method | String | The MCP tool or lifecycle method name |
params | Object | Method-specific arguments |
Sources: crates/mcb-domain/src/utils/tests/http_mcp.rs:43-75, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:90-100
Tool Registry
The transport layer exposes exactly 24 tools. Every tool must provide a valid JSON Object Schema for its inputSchema.
// Example of tool name matching in contract tests
const EXPECTED_TOOLS: &[&str] = &[
"analyze_code",
"index_repo",
"search_code",
"store_memory",
// ... total 24 tools
];
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:23-50
Conclusion
The MCP Transport Layer serves as the robust entry point for all agent interactions within MCB. By supporting both local Stdio and remote HTTP/SSE protocols, it provides flexibility for various AI workflows while maintaining strict architectural boundaries and security through provenance gating and execution flow validation.