Self-hosted Python MCP reference

Tool parameters, resource registrations and prompts for the self-hosted Python server in neo4j-agent-memory==0.7.0.

Overview

This page documents the self-hosted Python MCP server you run yourself with neo4j-agent-memory mcp serve (against a bolt or NAMS backend). It exposes memory capabilities via the Model Context Protocol for Claude Desktop, Claude Code, Cursor, and other MCP-compatible hosts.

The hosted NAMS backend also operates its own MCP server (OAuth-authenticated, a scope-dependent tool surface including ontology and skills) — see Hosted NAMS MCP Server. That one you connect to; this one you run.
Self-hosted MCP client, server profiles and backend-dependent memory operations
Figure 1. Self-hosted MCP client, server profiles, and backend-dependent memory operations

Registration and operation support are different. With NAMS, memory_add_preference, memory_add_fact, and direct relationship creation delegate to unsupported operations. Choose supported search types explicitly and review data scope. The self-hosted registration inventory does not describe the separate hosted service.

Tools are organized into two profiles:

  • Core (6 tools): Essential read/write cycle for memory operations

  • Extended (16 registered tools on Bolt; 20 on NAMS): Adds reasoning, entity, graph and query tools; four extra registrations are NAMS-specific

Start the server with a specific profile:

neo4j-agent-memory mcp serve --profile core      # 6 tools
neo4j-agent-memory mcp serve --profile extended   # 16 on Bolt / 20 on NAMS (default profile)

Core profile tools

memory_search

Search the selected memory types through the integration layer. With NAMS, pass memory_types=["messages", "entities"] to avoid the unsupported default preference search — see the fuller NAMS-limitations note under memory_add_preference below.

Parameter Description

query (required)

Natural language search query.

limit

Maximum results per memory type (default: 10).

memory_types

Types to search: messages, entities, preferences, traces. Defaults to messages, entities, preferences.

session_id

Requested message-search session. The checked Bolt implementation does not apply this filter; it is not an isolation guarantee.

threshold

Similarity threshold 0.0-1.0 (default: 0.7).

memory_get_context

Assembled context from enabled memory types. Retrieval can include results outside the current conversation; this is not an authorization boundary.

Parameter Description

session_id

Session to get context for (uses current session if not set).

query

Optional search query to focus context retrieval.

max_items

Maximum items per memory type (default: 10).

include_short_term

Include conversation history (default: true).

include_long_term

Include entities and preferences (default: true).

include_reasoning

Include similar reasoning traces (default: true).

memory_store_message

Store a message and invoke the configured extraction behavior. NAMS does not expose the Bolt preference-write API.

Parameter Description

content (required)

The message text content.

role

Message role: user, assistant, or system (default: user).

session_id

Session ID (uses current session if not set).

metadata

Optional metadata dict to attach.

memory_add_entity

Create or update an entity in the knowledge graph with POLE+O typing.

Parameter Description

name (required)

Entity name (e.g., "John Smith", "Acme Corp").

entity_type (required)

POLE+O type: PERSON, OBJECT, LOCATION, EVENT, ORGANIZATION.

subtype

Optional subtype (e.g., VEHICLE, COMPANY, ADDRESS).

description

Entity description.

aliases

Alternative names for the entity.

metadata

Additional metadata.

memory_add_preference

Record a preference for personalization. Bolt only; registration on NAMS does not make this write supported.

Parameter Description

category (required)

Preference category (e.g., food, music, communication_style).

preference (required)

The preference text (e.g., "Prefers dark mode").

context

Optional context about when/why the preference was expressed.

confidence

Confidence score 0.0-1.0 (default: 1.0).

memory_add_fact

Store a subject-predicate-object fact triple. Bolt only.

Parameter Description

subject (required)

The subject of the fact.

predicate (required)

The relationship.

object_value (required)

The object/value.

confidence

Confidence score 0.0-1.0 (default: 1.0).

valid_from

ISO date for when this fact becomes valid.

valid_until

ISO date for when this fact expires.

metadata

Additional metadata (e.g., scope, stack_tags, temporality).

Extended profile additional tools

memory_get_conversation

Retrieve full conversation history for a session.

Parameter Description

session_id (required)

The session ID to retrieve.

limit

Maximum messages to return (default: 50).

include_metadata

Include message metadata (default: true).

memory_list_sessions

List available conversation sessions with previews.

Parameter Description

limit

Maximum sessions to return (default: 20).

offset

Offset for pagination (default: 0).

memory_get_entity

Get detailed entity information with graph relationships.

Parameter Description

name (required)

Entity name to look up.

entity_type

Filter by POLE+O type (optional).

include_neighbors

Traverse graph for related entities (default: true).

max_hops

Relationship traversal depth, 1-3 (default: 1).

memory_export_graph

Export a subgraph as JSON for visualization or debugging.

Parameter Description

session_id

Filter to a specific session (optional).

memory_types

Types to include: short_term, long_term, reasoning. Defaults to all.

limit

Maximum nodes per memory type (default: 500).

memory_create_relationship

Create a typed relationship between two entities. Bolt only; the NAMS backend rejects this client-created relationship operation.

Parameter Description

source_name (required)

Name of the source entity.

target_name (required)

Name of the target entity.

relationship_type (required)

Relationship type in UPPER_SNAKE_CASE (e.g., WORKS_AT, FOUNDED).

description

Optional description of the relationship.

confidence

Confidence score 0.0-1.0 (default: 1.0).

memory_start_trace

Begin recording a reasoning trace for a complex task.

Parameter Description

session_id (required)

Session ID for the trace.

task (required)

Description of the task being solved.

metadata

Optional metadata (e.g., model name).

memory_record_step

Record a reasoning step within a trace.

Parameter Description

trace_id (required)

ID of the trace to add the step to.

thought

The reasoning for this step.

action

The action taken.

observation

The result or observation.

tool_name

Name of tool called in this step (optional).

tool_args

Arguments passed to the tool (optional).

tool_result

Result from the tool call (optional).

memory_complete_trace

Complete a reasoning trace with the final outcome.

Parameter Description

trace_id (required)

ID of the trace to complete.

outcome

Final outcome or result description.

success

Whether the task completed successfully (default: true).

memory_get_observations

Get observations and extracted insights for a session.

Parameter Description

session_id (required)

Session ID to get observations for.

Returns the three-tier context hierarchy: reflections (session summaries), observations (facts, decisions), and session statistics.

graph_query

Execute a read-only Cypher query against the knowledge graph.

Parameter Description

query (required)

Cypher query string (read-only only).

parameters

Query parameters as key-value pairs.

Write operations (CREATE, MERGE, DELETE, SET, REMOVE) are blocked for safety.

NAMS-specific extended registrations

The extended profile adds these four registrations when the client uses NAMS. “Platinum” in source comments names a client conformance tier, not a pricing or support commitment — see NAMS limits and behavior for what the conformance tiers mean.

Tool Parameters Return and current limitation

memory_set_entity_feedback

Required entity_id, feedback; optional user_identifier=None

JSON text with status, entity_id, feedback. The wrapper accepts but does not forward user_identifier; workspace authentication supplies service scope.

memory_get_entity_history

Required entity_id; limit=50

JSON text with entity_id and history. This wrapper does not forward limit to the client.

memory_get_entity_provenance

Required entity_id

JSON text containing the client’s provenance response, including available sources and extractors.

memory_get_reflections

Required session_id; limit=20

JSON text with session_id and reflections. This wrapper does not forward limit to the client.

These wrappers catch operation errors and return JSON text with an error field. A successful MCP protocol response therefore still needs its tool result inspected. Live service behavior and visibility require an authenticated check against the intended workspace.

Resources

The context URI is a resource template. Other rows are concrete resources. Registration does not bypass backend limitations; in particular, the preference resource cannot supply Bolt preference storage through NAMS.

URI Profile Description

memory://context/{session_id}

Core

Assembled context for a session (conversation + entities + preferences).

memory://entities

Extended

Catalog of all entities with names, types, and descriptions.

memory://preferences

Extended

All stored user preferences.

memory://graph/stats

Extended

Knowledge graph node/relationship counts.

Prompts

Name Profile Description

memory-conversation

Core

Initialize a memory-aware conversation. Loads context and guides memory tool usage.

memory-reasoning

Extended

Record a reasoning trace for a complex task with step-by-step guidance.

memory-review

Extended

Review stored knowledge and flag contradictions or outdated information.

Server instructions

The server sends behavioral instructions during MCP initialization that teach Claude:

  • To call memory_get_context at conversation start

  • To call memory_store_message for important user messages

  • To call memory_search when asked about past interactions

  • To use POLE+O entity types and UPPER_SNAKE_CASE relationship types

  • (Extended) To record reasoning traces for complex tasks

Transports

The server is built on FastMCP 4 (MCP Python SDK 2) and serves two transports:

Transport When to use

stdio (default)

Local hosts that launch the server as a child process: Claude Desktop, Claude Code, Cursor. The host owns stdin/stdout, so nothing else may write to them — the FastMCP startup banner is suppressed on this transport for that reason.

http

Streamable HTTP, the network transport in the current MCP spec. Use it for Cloud Run, Kubernetes, or any deployment where several clients share one server. streamable-http is accepted as an explicit spelling of the same thing.

Export the Aura credentials from the Aura connection setup before starting either transport. The server process connects to Aura through the bolt backend; its transport determines how the MCP host reaches that process.

# Local process, for a desktop host; memory is stored in Aura.
neo4j-agent-memory mcp serve --backend bolt \
  --uri "$NEO4J_URI" --user "$NEO4J_USERNAME"

# networked, Streamable HTTP on all interfaces
neo4j-agent-memory mcp serve --transport http --host 0.0.0.0 --port 8080 \
  --backend bolt --uri "$NEO4J_URI" --user "$NEO4J_USERNAME"

--transport sse is deprecated. The MCP specification replaced the legacy HTTP+SSE transport with Streamable HTTP, and FastMCP 4 deprecated it in turn. The flag is still accepted so existing launch configurations keep starting, but it logs a warning and serves Streamable HTTP. Switch to --transport http.

The endpoint path also changed with it: Streamable HTTP serves a single POST/GET endpoint at /mcp (no trailing slash; /mcp/ answers with a redirect), not the old /sse + /messages pair. Update client URLs alongside the flag.

CLI reference

The maintained options, defaults and environment precedence are in CLI reference. The core profile registers six tools; the extended profile registers sixteen with Bolt or twenty with NAMS.

Runnable example

examples/claude-code-team-memory/ wires this server (both profiles) and the hosted NAMS MCP server side by side in Claude Code, Claude Desktop and Cursor, with no agent code.

See also