MCP Protocol Server
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- README.md
- crates/mcb-domain/src/protocol.rs (Referenced via crates/mcb-domain/src/lib.rs)
- crates/mcb-server/src/transport/http_client.rs
- crates/mcb-server/tests/unit/mcp_server/mcp_protocol_tests.rs
- crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs
- crates/mcb-domain/src/utils/tests/http_mcp.rs
The MCP Protocol Server is a high-performance implementation of the Model Context Protocol (MCP) designed to provide AI agents with persistent memory, semantic code search, and architecture validation. It serves as the primary interface for MCP-compatible clients like Claude Desktop and Claude Code, allowing them to interact with a structured codebase and memory context through a standard JSON-RPC 2.0 interface.
The server operates within a Clean Architecture framework, where the protocol layer (handled by mcb-server) manages transports and routing, while the business logic is encapsulated in the mcb-domain crate. It supports multiple execution flows, including standard stdio for local integration and HTTP/SSE for remote or hybrid configurations.
Sources: README.md:1-12, AGENTS.md:120-125, crates/mcb-domain/src/lib.rs:44-53
Architecture and Components
The server architecture is structured into layers that enforce strict inward-only dependency flows. The mcb-server crate acts as the entry point, handling MCP protocol details, transport management (Axum HTTP, Stdio), and tool routing.
System Layering
- mcb-server: Handles MCP protocol versioning, transport layers (HTTP/SSE, Stdio), and routes tool calls to specific handlers.
- mcb-infrastructure: Manages Dependency Injection (via
linkme), configuration, and cross-cutting concerns like logging and tracing. - mcb-domain: Contains the core protocol types, entity definitions, and port traits that define the server's capabilities.
Sources: README.md:46-60, AGENTS.md:173-186
Component Interaction
The following diagram illustrates how a request flows from a client through the transport layer to the core handlers.
The transport layer abstracts the communication medium, ensuring that whether a request comes via stdin or HTTP, it is processed uniformly by the domain logic.
Sources: crates/mcb-server/src/transport/http_client.rs:175-200, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:114-130
Protocol Implementation
The server implements the MCP JSON-RPC 2.0 specification. It handles standard handshakes, capability discovery, and tool execution.
Protocol Standards
- JSON-RPC Version: Fixed to
"2.0". - Initialization: Clients must send an
initializerequest to negotiate protocol versions and discover server capabilities. - Success/Error Handling: Responses include either a
resultor anerrorobject with standard codes (e.g.,-32601for method not found,-32602for invalid params).
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_protocol_tests.rs:20-55, crates/mcb-domain/src/utils/tests/http_mcp.rs:77-110
Tool Execution Flow
When a tool is called, the server performs provenance gating to ensure execution safety and context awareness.
Data-plane tools (like index_repo or search_code) strictly reject requests that lack essential provenance fields such as session_id, repo_id, and operator_id.
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:114-135, crates/mcb-server/src/transport/http_client.rs:270-295
MCP Tools and Capabilities
The server exposes 24 public tools grouped into functional families. These tools are registered using the linkme distributed slice pattern, allowing for modular expansion without tight coupling.
| Family | Key Tools | Description |
|---|---|---|
| Search | search_code, search_memory | Semantic retrieval using vector embeddings. |
| Index | index_repo, clear_index | Repository analysis and vector store synchronization. |
| Memory | store_memory, get_memories | Persistent observation storage across agent sessions. |
| Validation | validate_code, list_rules | Architecture rule enforcement via mcb-validate. |
| VCS | list_repos, analyze_impact | Git-aware repository and branch analysis. |
Sources: README.md:37-44, AGENTS.md:202-212, crates/mcb-server/tests/unit/mcp_server/mcp_contract_tests.rs:31-56
Tool Schema Requirements
All registered tools must provide a valid JSON Schema for their input. The server enforces:
- Type: Must be
object. - Context Hiding: Fields used for internal provenance (e.g.,
repo_id,worktree_id) are automatically hidden from the public tool schemas to prevent manual override by agents.
Sources: crates/mcb-server/tests/unit/mcp_server/mcp_protocol_tests.rs:61-120
Transport Modes
The server supports diverse connectivity models to accommodate different agent environments.
Stdio Transport
Used primarily for local integration (e.g., Claude Desktop). The server reads requests from stdin and writes JSON-RPC responses to stdout.
HTTP and Hybrid Transport
The server can act as a bridge using the HttpClientTransport. This allows local agents to communicate with a remote MCB server while maintaining local context.
| Feature | Description |
|---|---|
| Secure Transport | Plain HTTP is only permitted for loopback addresses (127.0.0.1). Remote hosts require HTTPS. |
| Provenance Headers | Forwards workspace root, repo path, and session ID via custom HTTP headers (e.g., X-MCB-Workspace-Root). |
| Execution Flows | Supports EXECUTION_FLOW_HYBRID and EXECUTION_FLOW_SERVER_HYBRID for distributed processing. |
Sources: crates/mcb-server/src/transport/http_client.rs:65-120, crates/mcb-server/src/transport/http_client.rs:270-300
Summary
The MCP Protocol Server provides a robust, schema-validated interface for AI agents to interact with development environments. By enforcing Clean Architecture and strict provenance gating, it ensures that semantic search, memory persistence, and code analysis are performed securely and consistently across different transport layers. Its modular tool registry and support for both local (stdio) and remote (HTTP) communication make it a versatile core component of the MCB ecosystem.