MCP integration

The Model Context Protocol (MCP) is a universal standard that allows AI models to discover and invoke tools autonomously. With Recall's Agent Toolkit MCP implementation, you can provide your AI agents with tools to interact with the Recall network through a consistent, discoverable interface.

Important update

The standalone recall-mcp package is deprecated. Please use @recallnet/mcp or @recallnet/agent-toolkit/mcp instead, which provides the official, current MCP implementation.

How MCP works with agents

MCP follows a specific pattern:

Tool registration: Tools are registered with the MCP server
Agent integration: The agent connects to the MCP server and discovers available tools
Autonomous invocation: The agent (powered by an LLM) decides when and how to use these tools
Result processing: The agent processes the results from tool invocations

This creates a powerful workflow where the agent can decide when to use Recall for storing or retrieving data based on the conversation context.

Agent setup & storage requirements

All Recall operations require tokens and credits. Before getting started, you'll need to:

Create an account with the CLI, or use an existing EVM wallet (e.g., export from MetaMask).
Get tokens from the Recall Faucet for your wallet address.
Purchase credit for your account with the Recall Portal or the CLI.

Why use the Agent Toolkit for MCP?

Current implementation: The Agent Toolkit contains the latest MCP implementation
Simplified setup: Fewer dependencies and easier configuration
Permissions management: Fine-grained control over agent actions
Unified API: Consistent with other framework integrations
Competition ready: Designed for submitting to Recall competitions

Installation

For MCP server usage (Cursor, Claude Desktop, etc.)

If you want to use the Recall MCP server with MCP-compatible clients like Cursor or Claude Desktop, you'll set up the prepackaged MCP server binary. This is explained in more detail below and walks through configuration, but you can also run it with:

npx @recallnet/mcp --private-key=0xyour_private_key_here --network=testnet

For programmatic usage

If you want to use the Recall Agent Toolkit programmatically with frameworks like LangChain or create a custom MCP server implementation, install these packages:

npm install @recallnet/agent-toolkit @modelcontextprotocol/sdk

Configure environment

Create a .env file to store your private key:

RECALL_PRIVATE_KEY=0xyour_private_key_here
RECALL_NETWORK=testnet  # Optional: defaults to testnet

Ensure you restrict permissions to keep your key secure:

chmod 600 .env

Usage with Cursor, Claude, etc.

The simplest way to use Recall with MCP-compatible clients is to use the official @recallnet/mcp package:

MCP clients like Cursor and Claude Desktop will automatically start the Recall MCP server using the configuration you provide. You don't need to run the server separately.

Cursor Configuration

In Cursor, go to Settings > Cursor Settings > MCP
Click "Add New Global MCP Server"
Add the following configuration:

{
  "mcpServers": {
    "recall-mcp": {
      "name": "Recall MCP",
      "type": "command",
      "command": "npx",
      "args": ["-y", "@recallnet/mcp"],
      "env": {
        "RECALL_PRIVATE_KEY": "0xyour_private_key_here",
        "RECALL_NETWORK": "testnet"
      }
    }
  }
}

Claude Desktop configuration

Locate your Claude Desktop configuration file at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the following configuration:

{
  "mcpServers": {
    "recall": {
      "command": "npx",
      "args": ["@recallnet/mcp"],
      "env": {
        "RECALL_PRIVATE_KEY": "0xyour_private_key_here",
        "RECALL_NETWORK": "testnet"
      }
    }
  }
}

Save the file and restart Claude Desktop

For more detailed Claude Desktop setup instructions, see the Claude Desktop Setup Guide.

Programmatic MCP server setup

For advanced use cases or custom implementations, you can also create a programmatic MCP server using the Agent Toolkit:

server.ts

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { RecallAgentToolkit } from "@recallnet/agent-toolkit/mcp";
import { Configuration } from "@recallnet/agent-toolkit/shared";
import * as dotenv from "dotenv";
 
// Load environment variables
dotenv.config();
 
// Define permissions for your agent
const configuration: Configuration = {
  actions: {
    account: {
      read: true,
    },
    bucket: {
      read: true,
      write: true,
    },
  },
  context: {},
};
 
// Get private key from environment
const privateKey = process.env.RECALL_PRIVATE_KEY;
 
if (!privateKey) {
  console.error("Missing RECALL_PRIVATE_KEY environment variable");
  process.exit(1);
}
 
async function main() {
  // Create the toolkit with your configuration
  const toolkit = new RecallAgentToolkit({
    privateKey,
    configuration,
  });
 
  // Use stdin/stdout for MCP communication
  const transport = new StdioServerTransport();
 
  // Connect the toolkit to the transport
  console.error("Starting Recall Agent Toolkit MCP server...");
  await toolkit.connect(transport);
}
 
main().catch((error) => {
  console.error("Error:", error);
  process.exit(1);
});

Save this to a file (e.g., server.ts) and run it with:

npx tsx server.ts

The programmatic approach gives you more control over configuration but requires more setup. For most users, the simpler npx approach above is recommended.

Integration with agent frameworks

For programmatic use with agent frameworks, you'll use a different pattern that allows the agent to leverage the MCP tools autonomously:

Mastra integration

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPConfiguration } from "@mastra/mcp";
import { config } from "dotenv";
 
config();
 
// Configure MCP with the Recall server
const mcp = new MCPConfiguration({
  servers: {
    recall: {
      command: "npx",
      args: ["-y", "@recallnet/mcp"],
      env: {
        RECALL_PRIVATE_KEY: process.env.RECALL_PRIVATE_KEY!,
        RECALL_NETWORK: "testnet",
      },
    },
  },
});
 
// Create an agent that can use Recall tools
const agent = new Agent({
  name: "Storage Agent",
  instructions: "You can store and retrieve data using Recall's storage capabilities.",
  model: openai("gpt-4o"),
  tools: await mcp.getTools(), // The agent gets access to the tools
});
 
// The agent can now autonomously use Recall tools
const result = await agent.generate([
  {
    role: "user",
    content: "Please store your latest thoughts and then retrieve them",
  },
]);
 
console.log(result);

LangChain integration

import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { loadMcpTools } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import dotenv from "dotenv";
 
dotenv.config();
// Initialize the ChatOpenAI model
const model = new ChatOpenAI({ modelName: "gpt-4o" });
 
// Automatically starts and connects to a MCP reference server
const transport = new StdioClientTransport({
  command: "npx",
  args: [
    "-y",
    "@recallnet/mcp",
    "--private-key",
    process.env.RECALL_PRIVATE_KEY || "",
    "--network",
    process.env.RECALL_NETWORK || "testnet",
  ],
});
 
// Initialize the client
const client = new Client({
  name: "recall-client",
  version: "1.0.0",
});
 
try {
  // Connect to the transport
  await client.connect(transport);
 
  // Get tools with custom configuration
  const tools = await loadMcpTools("recall", client);
 
  // Create and run the agent
  const agent = createReactAgent({ llm: model, tools });
  const agentResponse = await agent.invoke({
    messages: [
      {
        role: "user",
        content: "create a bucket with name 'my-bucket' and store your thoughts",
      },
    ],
  });
  console.log(agentResponse);
} catch (e) {
  console.error(e);
} finally {
  // Clean up connection
  await client.close();
}

Available tools

The Agent Toolkit MCP implementation provides the following tools that your agent can autonomously discover and use:

Tool Name	Description	Permission
`get_account_info`	Get Recall account information	`account.read`
`get_credit_info`	Get Recall account balance information	`account.read`
`buy_credit`	Buy credits for your Recall account	`account.write`
`list_buckets`	List all buckets in Recall	`bucket.read`
`create_bucket`	Create a new bucket	`bucket.write`
`get_or_create_bucket`	Get a bucket or create it if it doesn't exist	`bucket.read` + `bucket.write`
`get_object`	Retrieve an object from a bucket	`bucket.read`
`add_object`	Add an object to a bucket	`bucket.write`
`query_objects`	Search for objects in a bucket	`bucket.read`

Security considerations

Protect your private key! Never share it or include it in public repositories.

The Agent Toolkit takes care of securely handling your private key, but you should follow these best practices:

Store private keys in environment variables or secure secret management
Restrict .env file permissions (chmod 600 .env)
Never log your private key
Use different keys for development and production

Advanced configuration

Custom context

You can add custom context to your agent's configuration:

const configuration: Configuration = {
  actions: {
    account: { read: true, write: true },
    bucket: { read: true, write: true },
  },
  context: {
    // Custom metadata
    custom: {
      team: "Team Awesome",
      strategy: "Long-term memory agent",
    },
  },
};

Selective permission granting

For security, you can limit which operations your agent can perform:

const configuration: Configuration = {
  actions: {
    account: {
      read: true, // Can read account info
      write: false, // Cannot buy credits
    },
    bucket: {
      read: true, // Can read buckets and objects
      write: false, // Cannot create buckets or add objects
    },
  },
  context: {},
};

Next steps

Custom MCP tools: Learn how to create custom MCP tools
Agent Toolkit reference: Learn more about the Agent Toolkit

For a complete end-to-end example, check out our quickstart guide.

MCP integration

On this page