What Is the MCP Transport in ai‑memory? Architecture and Implementation Guide

The MCP transport in ai‑memory is a standardized communication layer that exposes the storage engine’s tools over HTTP or stdio, allowing external agents like Claude Code, OpenCode, and Cursor to query and manage long‑term knowledge without accessing internal storage directly.

The ai‑memory project provides a persistent knowledge base for AI agents, and the MCP (Model Context Protocol) transport serves as the primary integration interface for external clients. Implemented via the rmcp crate within the ai‑memory‑mcp package, this transport wraps the core storage logic in a stable, version‑locked protocol that enforces authentication, scope resolution, and input sanitization.

Core Purpose of the MCP Transport

The transport serves two critical functions that keep the system secure and interoperable.

Expose MCP Tools Safely – Rather than allowing agents to touch the internal ai‑memory‑store directly, the transport surfaces a narrow, well‑defined tool surface including memory_query, memory_write_page, and memory_handoff_begin. This encapsulation ensures that all operations pass through authentication checks and scope resolution layers.

Provide a Stable Wire Protocol – By pinning the MCP protocol version in the rmcp dependency, the server guarantees that clients see a consistent set of tools regardless of client version. As noted in the source comments at [crates/ai-memory-mcp/src/lib.rs], this prevents "negotiated‑down" failures where older clients might lose access to newer tools.

How the MCP Transport Works

The implementation splits responsibilities across three architectural layers: the server skeleton, the public API surface, and client adapters.

The AiMemoryServer Skeleton and Tool Router

The heart of the transport lives in [crates/ai-memory-mcp/src/server.rs], which implements the AiMemoryServer struct. This server initializes with a reader pool and writer handle, then routes incoming MCP calls to the appropriate internal handlers.

use ai_memory_mcp::server::{AiMemoryServer, MEMORY_INSTRUCTIONS};

let server = AiMemoryServer::new(reader_pool, writer_handle);
let info = server.server_info();  // Returns tool metadata and MEMORY_INSTRUCTIONS

The router dispatches calls to tools like memory_query while maintaining strict validation of the X‑Memory‑Actor‑Session‑Id header for session scoping.

Protocol Versioning and Public API

The [crates/ai-memory-mcp/src/lib.rs] file exposes the public API and documents the version‑pinning strategy. It exports the AiMemoryServer struct and the MEMORY_INSTRUCTIONS constant, which contains the system prompts and tool definitions served to clients during initialization. The comment at the top of this file explicitly locks the MCP protocol version to prevent compatibility drift between the ai‑memory server and its clients.

Client Adapters and Session Management

For agents that only support stdio (such as Claude Code), the transport provides a bridge mechanism. The [crates/ai-memory-mcp/src/actor.rs] module handles extraction of the session ID from incoming headers, enabling the stdio bridge to inject the X‑Memory‑Actor‑Session‑Id header automatically.

The ai‑memory mcp‑bridge command creates this stdio‑to‑HTTP adapter, reading JSON-RPC messages from stdin and forwarding them to the HTTP server. For setup instructions across various client CLIs, see [docs/mcp‑install.md].

Running and Configuring the MCP Transport

You can start the transport in stateless HTTP mode for simple request/response cycles or enable stateful SSE streams for persistent connections.

Start a Stateless HTTP Server

ai-memory serve --transport http   # Listens on http://127.0.0.1:49374/mcp

Query the Memory Store via curl

curl -X POST http://127.0.0.1:49374/mcp \
  -H 'Content-Type: application/json' \
  -d '{
        "tool": "memory_query",
        "args": { "q": "how to embed vectors" },
        "request_id": "demo-1"
      }'

Install the Stdio Bridge for Claude Code

ai-memory install-mcp --client claude-code --session-aware --apply

This generates a configuration that runs ai-memory mcp-bridge, wrapping the HTTP transport in a stdio interface that Claude Code can consume while automatically injecting the session identifier.

Summary

• The MCP transport acts as the secure gateway between external agents and the ai‑memory storage engine, implemented in the ai‑memory‑mcp crate using the rmcp library.
• AiMemoryServer in [crates/ai-memory-mcp/src/server.rs] routes tool calls and enforces session scoping without exposing internal storage details.
• Version pinning documented in [crates/ai-memory-mcp/src/lib.rs] ensures protocol stability and prevents feature downgrade attacks.
• Client adapters in [crates/ai-memory-mcp/src/actor.rs] and the mcp‑bridge command provide stdio compatibility for agents that do not support native HTTP MCP connections.

Frequently Asked Questions

What agents are compatible with the ai‑memory MCP transport?

Any client that supports the Model Context Protocol over HTTP or stdio can connect, including Claude Code, OpenCode, Cursor, and custom agents. The [docs/mcp‑install.md] file provides specific registration commands for each supported client.

How does the MCP transport handle authentication?

Authentication and scope resolution occur at the transport layer before requests reach the storage engine. The server extracts session identifiers from the X‑Memory‑Actor‑Session‑Id header—handled by the actor logic in [crates/ai-memory-mcp/src/actor.rs]—and validates permissions against the requested wiki namespace or handoff context.

Can I run the MCP transport without HTTP?

Yes. While the server natively speaks HTTP (stateless on /mcp or stateful via SSE), you can use the ai‑memory mcp‑bridge command to create a stdio wrapper. This bridge reads JSON-RPC from standard input and forwards to the HTTP endpoint, enabling use with clients that only support stdio transport.

What is the difference between stateless and stateful MCP modes?

Stateless mode handles each tool call as an independent HTTP POST request to /mcp, suitable for simple queries. Stateful mode maintains a persistent Server‑Sent Events (SSE) stream, allowing the server to push asynchronous notifications and maintain long‑running session contexts required for handoff operations and consolidation tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}