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

> Discover the MCP transport in ai-memory. This guide explains how this standardized HTTP/stdio layer enables external agents to query and manage long-term knowledge efficiently.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: architecture
- Published: 2026-09-10

---

**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.

```rust
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

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

```

### Query the Memory Store via curl

```bash
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

```bash
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.