Mastra AI

Mastra supports MCP servers natively, which makes adding xmemory straightforward — paste a prompt into your AI-assisted IDE and the integration is done.

For the full tool reference, see the MCP guide. For direct HTTP API usage, see the TypeScript guide.

---

Setup

API key: To use xmemory APIs or integrations, 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.

Scaffold a Mastra project and add MCP support:

npm create mastra@latest my-xmemory-agent
cd my-xmemory-agent
npm install @mastra/mcp

Add your keys to .env:

XMEM_AUTH_TOKEN=your-token-here
ANTHROPIC_API_KEY=your-anthropic-key

---

Add xmemory

From your Mastra project directory, give this prompt to an AI-assisted IDE (Cursor, Windsurf, Claude Code, etc.):

Integrate the `xmemory` MCP server with this Mastra instance.

Add `@mastra/mcp` to package.json if not already present.

Create an MCP client that:
- Reads XMEM_AUTH_TOKEN from the environment (throw if missing).
- Connects to https://mcp.xmemory.ai/ with a Bearer auth header.

Load the MCP tools via listTools() and export them.

Create an `xmemory` Agent wired to those tools with these instructions:

> You are the xmemory assistant. You help users manage and query their
> xmemory instance:
> - Create and configure new instances, generate or enhance schemas,
>   connect and disconnect from instances.
> - Use the xmemory_admin_* tools to perform administrative and schema
>   operations as requested.
> - Be concise and confirm what you did after each action.

Register the agent in the Mastra instance alongside any existing agents.

That’s it. The agent now has access to all 6 xmemory MCP tools — write, write_async, write_status, read, get_instance_id, and get_instance_schema. See the MCP — Tools reference for details on each.

---

Reference

The prompt above produces files like the ones below. Use these to verify the output or to set things up manually.

MCP client — src/mastra/mcp.ts

import { MCPClient } from '@mastra/mcp';

if (!process.env.XMEM_AUTH_TOKEN) {
  throw new Error('XMEM_AUTH_TOKEN environment variable is required');
}

export const xmemoryMcp = new MCPClient({
  id: 'xmemory',
  servers: {
    xmemory: {
      url: new URL('https://mcp.xmemory.ai/'),
      requestInit: {
        headers: {
          Authorization: `Bearer ${process.env.XMEM_AUTH_TOKEN}`,
        },
      },
    },
  },
});

Tool loader — src/mastra/tools/xmemory.ts

import { xmemoryMcp } from '../mcp';

let xmemoryTools: Record<string, any> = {};
try {
  xmemoryTools = await xmemoryMcp.listTools();
} catch (err) {
  console.error('Failed to load xmemory MCP tools:', err);
}

export { xmemoryTools };

Agent — src/mastra/agents/xmemory.ts

import { Agent } from '@mastra/core/agent';
import { anthropic } from '@ai-sdk/anthropic';
import { xmemoryTools } from '../tools/xmemory';

export const xmemoryAgent = new Agent({
  name: 'xmemory-agent',
  model: anthropic('claude-sonnet-4-20250514'),
  instructions:
    'You are the xmemory assistant. You help users manage and query their xmemory instance: ' +
    'create and configure new instances, generate or enhance schemas, connect and disconnect from instances. ' +
    'Use the xmemory_admin_* tools to perform administrative and schema operations as requested. ' +
    'Be concise and confirm what you did after each action.',
  tools: { ...xmemoryTools },
});

Registration — src/mastra/index.ts

import { Mastra } from '@mastra/core';
import { xmemoryAgent } from './agents/xmemory';

export const mastra = new Mastra({
  agents: { xmemoryAgent },
});