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. Get one from the xmemory console. 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_API_KEY=your-api-key-here
XMEM_INSTANCE_ID=your-instance-id
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_API_KEY and XMEM_INSTANCE_ID from the environment (throw if missing).
- Connects to https://mcp.xmemory.ai/instance/<XMEM_INSTANCE_ID> with the API key as the 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 exact set of tools the agent sees depends on the connection type chosen at MCP login. With the instance connection type, the agent gets 9 default tools — 6 bound (get_instance_id, get_instance_schema, write, write_async, write_status, read) and the 3-tool schema-evolution suggestion engine (review_suggestions, decide_suggestions, apply_pending_decisions) — plus an opt-in Schema management group (5 more). With the admin connection type it instead gets the schema and instance-management tools (admin_*). See the MCP — Tools reference for full details.

Note on auth. This headless setup sends your account API key directly as the Bearer token on the /instance/<instance_id> shortcut path — no OAuth exchange needed. The instance is bound by the URL path, so tool calls don’t pass instance_id. See the MCP guide for the other connection options.

---

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_API_KEY || !process.env.XMEM_INSTANCE_ID) {
  throw new Error('XMEM_API_KEY and XMEM_INSTANCE_ID environment variables are required');
}

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

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-6'),
  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 },
});