Add an MCP server to a context graph project

Available on NAMS: No. The procedure on this page needs the Bolt backend. With the hosted NAMS backend its operations are unavailable: depending on the call, the client raises NotSupportedError, AttributeError or TypeError, or ignores a Bolt-only setting or argument (NAMS manages embedding and extraction server-side). See the backend capabilities reference for what NAMS provides instead.

To let an MCP client inspect a context graph application’s memory, run the self-hosted Python MCP server against the application’s Bolt database. The server needs compatible memory labels and indexes; connecting to an arbitrary domain graph does not automatically adopt it.

Prerequisites

  • A working application, such as one scaffolded with create-context-graph, with its database URI, database name and authorized credentials.

  • Python 3.10+ and an OpenAI key for this example’s embedding provider. The command below installs neo4j-agent-memory[mcp,openai]==0.7.0.

  • An MCP client that supports launching a local stdio process.

  • For an existing non-memory graph, complete graph adoption and its dry run first.

This procedure adds a second reader/writer of the same database. It does not create application-level authorization or automatically share a conversation between the web application and MCP host.

1. Install and check the server command

In the application’s Python project, add the MCP and OpenAI extras with its normal dependency manager. For a project managed by uv:

uv add 'neo4j-agent-memory[mcp,openai]==0.7.0'
uv run neo4j-agent-memory mcp serve --help

Confirm the selected command exposes --backend, --database, --profile and --transport. Resolve its executable path for the MCP host rather than relying on the GUI application’s shell PATH.

2. Configure a local stdio process

Use the Aura connection setup for the application’s dedicated AuraDB instance. Adapt this entry in your MCP client’s configuration. Replace the executable path, database settings and secrets with your application values. The client configuration file location depends on the installed host. Copy the Aura username into NEO4J_USER, the CLI’s supported alias; JSON values below are literal strings, not shell expressions.

{
  "mcpServers": {
    "context-graph": {
      "command": "/absolute/path/to/project/.venv/bin/neo4j-agent-memory",
      "args": [
        "mcp", "serve", "--backend", "bolt",
        "--database", "neo4j", "--profile", "extended"
      ],
      "env": {
        "NEO4J_URI": "neo4j+s://<instance-id>.databases.neo4j.io",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "replace-with-your-Aura-password",
        "OPENAI_API_KEY": "replace-with-provider-key"
      }
    }
  }
}

Use the same supported embedding provider/index dimensions as the application. This CLI’s default model-backed setup needs its provider key; other provider choices require explicit configuration as described in CLI reference. Store secrets using the host’s supported configuration mechanism and do not commit this populated file.

For an HTTP deployment, use --transport http with the /mcp endpoint and an explicit authentication arrangement. See transports and deployment routes rather than exposing a local example as a public service.

3. Verify tool registration and memory readback

  1. Restart or reconnect the MCP host and inspect tools/list. The extended Bolt server registers sixteen tools.

  2. Ask the host to call memory_store_message with a unique synthetic message and an explicit session ID, such as docs-context-graph-check.

  3. Call memory_get_conversation with that same session ID and verify the exact stored content.

  4. Inspect that conversation from the web application’s explicitly scoped history path. Check returned content, not a generic semantic-search hit.

The write/readback proves shared storage for that session. A domain entity will appear in memory search only when it has the expected labels, searchable data and compatible embedding/index setup. Review failed tool results; a protocol-level success can contain an operation error.

Integrate application context deliberately

The shipped MemoryIntegration needs async with or an explicit connection lifecycle before use. Its session strategy chooses identifiers; it does not authorize reads. per_conversation creates a conversation identifier, per_day derives a daily identifier and persistent derives a stable one. Matching strategy names in two processes do not alone prove they resolved the same ID.

Use the scope reference when combining recent history with long-term retrieval. Global entity/preference searches can contribute content outside a conversation. For an application that needs a particular transcript, retain and pass its exact conversation ID.

See also