MCP Tools for Agent Memory: A Technical Guide

What Is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Instead of building custom integrations for every LLM provider, MCP defines a universal JSON-RPC interface that any model can use to discover, invoke, and receive results from tools. Think of it as USB for AI — a single connector that works everywhere.

HatiData implements a full MCP server exposing 24 tools across five categories: memory management, chain-of-thought logging, semantic triggers, branch isolation, and query governance. Any MCP-compatible client — Claude Desktop, Cursor, Claude Code, or your own application — can connect to HatiData's MCP server and immediately gain access to persistent, searchable, auditable agent memory.

The MCP server runs alongside the main data proxy. It speaks JSON-RPC 2.0 over HTTP with Server-Sent Events (SSE) for streaming responses. Authentication uses the same API keys as the rest of HatiData, so there is no separate credential management.

Memory Tools: The Core Four

The most frequently used MCP tools are the four memory operations. These give agents the ability to remember information across sessions, search their memory semantically, and maintain persistent state.

store_memory

The store_memory tool writes a new memory entry into the agent's persistent store. Each memory has a namespace for logical grouping, content as free-form text, and optional metadata as key-value pairs. Behind the scenes, the content is embedded into a vector representation using the embedding service and stored in both the query engine (for SQL queries) and the vector index (for vector search).

{
  "tool": "store_memory",
  "arguments": {
    "namespace": "customer-interactions",
    "content": "User prefers weekly status reports delivered on Monday mornings. They are in the APAC timezone (UTC+8) and prefer concise bullet-point summaries over detailed narratives.",
    "metadata": {
      "user_id": "usr_8x9k2m",
      "importance": "high",
      "category": "preferences"
    }
  }
}

The response includes a memory_id (UUID) that can be used to reference this specific memory later. The embedding is dispatched asynchronously — the tool returns immediately while the vector representation is computed in the background by the embedding service.

search_memory

The search_memory tool performs hybrid retrieval across the agent's memory store. It accepts a natural language query, an optional namespace filter, and a limit on the number of results. The search pipeline first performs approximate nearest neighbor (ANN) lookup in the vector index using the query's embedding, then joins the results with structured metadata for filtering and ranking.

{
  "tool": "search_memory",
  "arguments": {
    "query": "What are the user's reporting preferences?",
    "namespace": "customer-interactions",
    "limit": 5,
    "min_similarity": 0.7
  }
}

The response returns matching memories ranked by relevance, each with a similarity score, the original content, metadata, and timestamps. The min_similarity threshold filters out weak matches — memories below this cosine similarity score are excluded from results.

get_agent_state and set_agent_state

These two tools manage persistent key-value state for agents. Unlike memories (which are searchable documents), agent state is for structured data that the agent needs to track across sessions — things like current task progress, configuration preferences, or workflow checkpoints.

{
  "tool": "set_agent_state",
  "arguments": {
    "key": "onboarding_progress",
    "value": {
      "step": 3,
      "completed_steps": ["welcome", "data_import", "schema_setup"],
      "remaining_steps": ["query_test", "deploy"],
      "started_at": "2026-02-28T10:00:00Z"
    }
  }
}

State values can be any JSON-serializable object. They are stored in the query engine with the agent's identity and namespace, making them queryable via SQL for debugging and analytics. The get_agent_state tool retrieves the current value for a given key, returning null if the key has not been set.

Beyond Memory: The Full Tool Suite

While memory tools handle the core read/write loop, HatiData's MCP server exposes 20 additional tools across four more categories.

Chain-of-Thought Tools (3 tools)

The CoT tools give agents the ability to log their reasoning process into an immutable, hash-chained ledger. Each reasoning step is linked to the previous one via cryptographic hashing, creating a tamper-proof audit trail.

• log_reasoning_step — Appends a new step to the current session's reasoning chain. Accepts a step type (observation, hypothesis, decision, action, reflection, error, planning, evaluation, tool_call, tool_result, memory_recall, or context_switch), content, and optional confidence score.
• replay_decision — Retrieves the full reasoning chain for a given session, allowing the agent (or a human reviewer) to understand exactly how a decision was reached.
• get_session_history — Lists all reasoning sessions for the current agent, with summary statistics like step count, duration, and chain integrity status.

Semantic Trigger Tools (4 tools)

Semantic triggers allow agents to register interest in conceptual events and receive notifications when relevant content appears in the system.

• register_trigger — Creates a new trigger with a concept description, similarity threshold, cooldown period, and dispatch action.
• list_triggers — Returns all active triggers for the current organization.
• delete_trigger — Removes a trigger by ID.
• test_trigger — Evaluates a test input against all registered triggers without firing any actions, useful for debugging threshold tuning.

Branch Isolation Tools (5 tools)

Branch tools enable agents to create isolated copies of their data environment for safe exploration and what-if analysis.

• branch_create — Creates a new branch with zero-copy views of the main schema.
• branch_query — Executes a query within a specific branch's isolated environment.
• branch_merge — Merges branch changes back into the main schema using a specified conflict resolution strategy.
• branch_discard — Discards a branch and cleans up its resources.
• branch_list — Lists all active branches with their creation time, row counts, and materialization status.

Query and Governance Tools (7 tools)

These tools handle direct data querying, schema inspection, and governance operations.

• query — Executes a SQL query against the agent's data warehouse.
• list_tables — Returns all tables in the current namespace with row counts and column summaries.
• describe_table — Returns the full schema for a specific table.
• context_search — Performs semantic search across table descriptions and column names.
• explain_query — Returns the query execution plan without running the query.
• get_quota — Returns the agent's current resource usage and remaining quota.
• rotate_key — Generates a new API key and invalidates the previous one.

Configuring MCP Clients

Claude Desktop

To connect Claude Desktop to HatiData, add the following to your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "hatidata": {
      "url": "http://localhost:5440/mcp/sse",
      "headers": {
        "Authorization": "Bearer hd_live_your_api_key_here"
      }
    }
  }
}

Once configured, Claude Desktop will automatically discover all 24 tools and make them available in conversation. You can ask Claude to store memories, search past interactions, log reasoning steps, and manage branches — all through natural language.

Cursor

For Cursor IDE, add the MCP server configuration to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "hatidata": {
      "url": "http://localhost:5440/mcp/sse",
      "headers": {
        "Authorization": "Bearer hd_live_your_api_key_here"
      }
    }
  }
}

Claude Code

For Claude Code CLI, add to your project's .claude/mcp.json:

{
  "mcpServers": {
    "hatidata": {
      "type": "sse",
      "url": "http://localhost:5440/mcp/sse",
      "headers": {
        "Authorization": "Bearer hd_live_your_api_key_here"
      }
    }
  }
}

Performance Characteristics

The MCP server is designed for high-throughput agent workloads. Key performance characteristics include:

• Connection capacity: 10,000+ concurrent MCP connections per server instance
• Memory store latency: Sub-millisecond writes, single-digit millisecond reads for most queries
• Search latency: Under 5ms p50 for hybrid search across millions of memories
• Embedding pipeline: Asynchronous batch processing with configurable batch size and flush interval
• Branch creation: Near-instant via zero-copy schema views

The MCP server uses connection pooling internally, so each connected client does not consume a dedicated thread. Backpressure is handled via bounded channels — if the embedding pipeline falls behind, store_memory calls will still return immediately while embeddings queue up for processing.

Practical Example: A Research Agent

Here is a complete workflow showing how a research agent might use multiple MCP tools in a single session:

1. 1The agent receives a research task and uses store_memory to record the task parameters
2. 2It uses search_memory to find relevant prior research on the same topic
3. 3It creates a branch with branch_create to safely explore a hypothesis
4. 4It logs each reasoning step with log_reasoning_step as it analyzes data
5. 5It runs queries within the branch using branch_query
6. 6If the hypothesis is validated, it merges the branch with branch_merge
7. 7It stores the final conclusions as a new memory with store_memory

This entire workflow uses 7 of the 24 available tools, all through the same MCP connection. The agent does not need to know about the underlying infrastructure — it just calls tools with natural-language-friendly arguments and gets structured results back.

Next Steps

The MCP protocol is evolving rapidly, and HatiData tracks the latest specification updates. For a complete reference of all 24 tool schemas with parameter types and example responses, see the MCP Tools API documentation. For framework-specific integration guides, check the cookbooks for LangChain, CrewAI, and OpenAI Agents SDK.