memory-mcp

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: memory-mcp-claude-code, memory-mcp-codex -->

Connect an MCP Client to Memory

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

Overview

Any Model Context Protocol (MCP) client, such as Claude Code or Codex, can connect directly to memory without using the [agent-engine-sdk-memory](https://www.mongodb.com/docs/agentengine/add-features/memory-only.md#std-label-agent-engine-memory-only SDK. Use this MCP connection to give that client memory, instead of writing Python code against the SDK yourself. In this guide, you can learn how to connect an MCP client to memory and record and recall conversation turns.

Tip:

To learn more about memory, see [How Memory Works](https://www.mongodb.com/docs/agentengine/add-features/memory-types.md#std-label-agent-engine-memory-architecture in the Add Memory to Your Agent guide.

The MCP server exposes three tools:

  • record_turn: Records one short-term conversation turn. This is the only write operation among the three tools.

  • build_context: Retrieves memory relevant to a query and formats it as context.

  • search_memories: Searches long-term memory by type.

A background process extracts [long-term memories](https://www.mongodb.com/docs/agentengine/add-features/memory-types.md#std-label-agent-engine-memory-architecture from recorded turns asynchronously. To create a long-term memory directly instead of waiting for extraction, use the agent-engine-sdk-memory SDK described in [Use the Standalone Memory Service.](https://www.mongodb.com/docs/agentengine/add-features/memory-only.md#std-label-agent-engine-memory-only

Prerequisites

Ensure that you have the following prerequisites before you begin:

  • A project on the Atlas Agent Engine. To find your project ID, see [View Projects.](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-projects

  • Memory enabled on that project, which requires the following components:

  • The MONGODB_URI, VOYAGE_API_KEY, and an LLM API key (such as ANTHROPIC_API_KEY) uploaded as project secrets.

  • A running memory runtime. If you don't have a runtime, run the agentengine memory apply --wait command to provision the runtime. Wait until the runtime reports as ready before you continue.

To learn how to configure these prerequisites, see [Configure Memory.](https://www.mongodb.com/docs/agentengine/add-features/memory.md#std-label-agent-engine-manage-memory

  • A project service account with the PROJECT_OWNER role. Run the following command to create one, replacing <name> with a name for the service account:

bash agentengine service-account create <name> --role PROJECT_OWNER

Important:

Save the client ID and client secret that the command returns. The Atlas Agent Engine shows the client secret only once.

Get an Access Token

To obtain an access token, run the following command, replacing <client-id> with your service account's client ID:

read -r -p "Client ID: " CLIENT_ID
curl --fail-with-body --silent --show-error --user "$CLIENT_ID" \
  --data grant_type=client_credentials \
  https://agentengine.mongodb.com/api/v1/oauth/token

curl prompts for the client secret without echoing it to the terminal. Copy the access_token field's value from the returned JSON object for use in the next section.

Important:

The access token expires after one hour. If you hard-code the token in your MCP client configuration, the connection stops working after expiration. To restore the connection, rerun the preceding command to obtain a new token, and then update the configuration.

Connect Your MCP Client

Any MCP client that supports Streamable HTTP transport can connect to memory by using the following URL. Replace <project_id> with your project ID.

https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp

Send the access token from the previous section as an Authorization: Bearer <access-token> header.

Select the tab that corresponds to your MCP client for an example of sending the access token when you add the server:

Claude Code

Run the following command to add memory as an MCP server, replacing <project_id> and <access-token> with your project ID and access token. The --scope user flag makes the server available in every project.

claude mcp add --scope user --transport http project-memory \
  https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp \
  --header "Authorization: Bearer <access-token>"

Alternatively, add the following configuration to ~/.claude.json, which the Claude Code CLI and the Claude Code VS Code extension share:

{
  "mcpServers": {
    "project-memory": {
      "type": "http",
      "url": "https://agentengine.mongodb.com/api/v1/projects/<project_id>/mcp",
      "headers": {
        "Authorization": "Bearer <access-token>"
      }
    }
  }
}

Verify the Connection

After you add the MCP server, restart your MCP client and confirm that it lists the three memory tools and that a recorded turn becomes searchable.

  1. Confirm that the client lists the memory tools.

Open your MCP client and confirm that it lists exactly three tools from the project-memory server: record_turn, build_context, and search_memories.

  1. Record a conversation turn.

Call record_turn twice with a distinctive fact, a user_id, and a session_id. Record a user role turn followed by an assistant role turn. The following example records a fact about a home airport:

text record_turn(user_id="user_1", session_id="session_1", role="user", content="I always fly out of Boston.") record_turn(user_id="user_1", session_id="session_1", role="assistant", content="Got it, Boston is saved as your home airport.")

  1. Retrieve the recorded turn as context.

Call build_context with the same user_id and session_id that you used in the preceding step, and a query that matches the recorded fact. The recorded turn appears immediately, because build_context includes recent short-term turns:

text build_context(user_id="user_1", session_id="session_1", query="Where should the flight book from?")

  1. Search long-term memory for the extracted fact.

Wait a few minutes for the background extraction process to consolidate the recorded turn into a long-term memory. Then, call search_memories with the same user_id, a matching query, and a memory type:

text search_memories(user_id="user_1", query="home airport", type="semantic")

If the fact does not appear, wait longer and search again. Extraction runs asynchronously and might not finish immediately after you record a turn.