MCP

xmemory exposes a Model Context Protocol server over Streamable HTTP. Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, pydantic-ai, LangChain, Mastra, or a plain SDK call — can connect and get access to xmemory’s read and write tools with no custom code.

Video tutorial coming soon — we’re putting together a step-by-step video walkthrough showing how to connect xmemory via MCP to products like Claude Code, ChatGPT, and Codex using their native MCP connectors. Stay tuned!

Authentication

API key: To use xmemory APIs or integrations (including MCP), you need an API key. Please register your interest at https://xmemory.ai and we will reach out to give access. Copy and securely store the key. Never share your API key publicly.

The token is a bearer token that encodes which instance the session is bound to. You don’t pass instance_id in tool calls — the server resolves it from the token automatically.

Authorization: Bearer <your-token>

Connection


URL	`https://mcp.xmemory.ai/`
Transport	Streamable HTTP
Auth	Bearer token in the `Authorization` header

Any MCP client that supports Streamable HTTP can connect. Here is the minimal pattern:

{
  "mcpServers": {
    "xmemory": {
      "url": "https://mcp.xmemory.ai/",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

For framework-specific setup, see the integration guides: Pydantic, LangChain, Mastra AI.

Tools

The xmemory MCP server exposes 11 tools to instance connections: 6 bound tools that operate on the instance bound at login, and 5 explicit-instance tools that take an instance_id parameter for multi-instance access.

Tool descriptions are dynamic — on each list_tools() call, the server fetches your instance’s schema and appends a summary of its object types and relations to each tool description. This means the LLM sees tool descriptions tailored to your specific instance, making it more likely to use the tools correctly.

`get_instance_id`

Returns the instance ID bound to the current session (e.g. "inst_abc123").

Parameters: none.

Useful for display, logging, or confirming which instance the agent is operating on.

`get_instance_schema`

Returns the full instance schema as a JSON string — object types with their fields, relations, deduplication keys, and descriptions.

Parameters: none.

The LLM can call this to understand what kinds of data the instance stores, which helps it formulate better write and read calls.

`write`

Extracts structured entities from free-form text and persists them. Synchronous — blocks until the data is fully committed.

Parameter	Type	Description
`text`	`string`	Free-form text containing facts to extract and remember
`session_id`	`string \| null`	Optional session ID for tracing (e.g. `claude-qwxhjkmrtz`)

Returns {"status": "ok"} on success.

Internally, the server runs a two-phase pipeline: an LLM extracts structured objects according to your instance’s schema, then a diff engine compares them against existing data and applies inserts, updates, and deletes.

Because write blocks until committed, you can call read immediately after and get consistent results.

`write_async`

Same as write, but enqueues the operation and returns immediately with a write_id.

Parameter	Type	Description
`text`	`string`	Free-form text containing facts to extract and remember
`session_id`	`string \| null`	Optional session ID for tracing

Returns {"status": "ok", "write_id": "<uuid>"}.

Important: do not call read immediately after write_async — the data may not be committed yet. Use write_status to poll, or use write (synchronous) when you need to read right after.

`write_status`

Checks the status of an async write previously submitted via write_async.

Parameter	Type	Description
`write_id`	`string`	The write ID returned by `write_async`

Returns:

{
  "status": "ok",
  "write_id": "<uuid>",
  "write_status": "queued | processing | completed | failed | not_found",
  "error_detail": "<string or null>",
  "completed_at": "<ISO timestamp or null>"
}

`write_status`	Meaning
`queued`	Waiting to be picked up
`processing`	Currently being extracted and applied
`completed`	Successfully committed — safe to `read`
`failed`	Extraction or persistence failed; see `error_detail`
`not_found`	No write with this ID exists

`read`

Queries the instance and returns a natural-language answer.

Parameter	Type	Description
`query`	`string`	A natural-language question about the stored data
`session_id`	`string \| null`	Optional session ID for tracing

Returns a JSON string with an answer field — a human-readable response synthesized from the structured data (capped at 1,000 characters).

Internally, the server translates the question into SQL against the instance’s knowledge graph, executes it with automatic retry and empty-result verification, and formats the result into a plain-text answer.

Explicit-instance tools

These take instance_id as a parameter so a single connection can operate across multiple instances.

Tool	Parameters	Description
`extract`	`instance_id`, `text`	Extract structured data from text. Extraction only — does not persist.
`write_to`	`instance_id`, `text`	Synchronous write to a specific instance.
`write_to_async`	`instance_id`, `text`	Async write to a specific instance; returns `write_id`.
`write_to_status`	`instance_id`, `write_id`	Poll the status of an async write.
`read_from`	`instance_id`, `query`	Query a specific instance.

Admin tools

Selecting the admin connection type at login switches the tool surface to schema generation and instance lifecycle management. All admin tools are prefixed admin_. The admin connection is stateful — it tracks whether you are currently connected to a specific instance, and several tools require that connection.

Important: never hand-write YAML schemas. Always use admin_generate_schema or admin_enhance_schema to produce a valid schema, then pass the result to admin_create_instance or admin_update_instance_schema.

Schema management

Tool	Parameters	Description
`admin_generate_schema`	`schema_description`	Generate a YAML schema from a free-form description.
`admin_enhance_schema`	`schema_description`, `schema_to_improve`	Improve an existing YAML schema.

Stateful instance lifecycle (operate on the connected instance, or change connection state)

Tool	Parameters	Description
`admin_create_instance`	`schema_yaml`, optional `cluster_id`, `name`, `description`, `instance_config`	Create a new instance. Requires being disconnected.
`admin_connect_instance`	`instance_id`	Connect to an existing instance. Fails if already connected.
`admin_disconnect_instance`	—	Disconnect from the current instance.
`admin_get_instance_id`	—	Return the connected instance ID (empty string if disconnected).
`admin_get_instance_schema`	—	Return the YAML schema of the connected instance.
`admin_update_instance_schema`	`schema_yaml`	Update the connected instance’s schema.
`admin_update_instance_config`	`instance_config`	Update per-instance model config overrides.

Cluster and instance management (require API key)

Tool	Parameters	Description
`admin_list_clusters`	—	List clusters accessible to the API key.
`admin_get_cluster`	`cluster_id`	Get a single cluster by ID.
`admin_list_instances`	`cluster_id`, optional `verbose`	List instances in a cluster.
`admin_list_own_instances`	optional `verbose`	List all instances across linked clusters.
`admin_get_instance_by_id`	`instance_id`	Get instance metadata.
`admin_delete_instance_by_id`	`instance_id`	Delete an instance.
`admin_get_instance_schema_by_id`	`instance_id`	Get schema by instance ID.
`admin_update_instance_schema_by_id`	`instance_id`, `schema_yml` or `schema_json`	Update schema by instance ID.
`admin_update_instance_metadata_by_id`	`instance_id`, `name`, optional `description`	Replace instance name/description.
`admin_patch_instance_metadata_by_id`	`instance_id`, optional `name`, `description`	Partially update instance metadata.

Sync vs async writes

Use write when you need to read the data back immediately — it blocks until committed, guaranteeing consistency.

Use write_async + write_status when throughput matters more than immediate consistency — the client isn’t blocked, and you can poll for completion later.

Error handling

All tools return {"error": "<message>"} as a JSON string on failure rather than raising exceptions, so the MCP client always gets a parseable response. Common errors:

Error	Cause
`"no instance bound to this session"`	Token is invalid or not linked to an instance
`"text size (N bytes) exceeds maximum (M bytes)"`	Write payload too large (limit: 1 MB)
`"write queue not ready"`	Background processor hasn’t started
`"write failed: <detail>"`	Extraction or persistence failure