Authentication

This guide explains authentication methods for the Recall Agent Toolkit, best practices for securing your credentials, and advanced techniques for managing authentication in different environments. The Recall Agent Toolkit authenticates with the Recall network using a private key, which is used to sign transactions. Properly securing this key is essential for the security of your application.

Authentication methods

Private key authentication

The most common way to authenticate is by providing your private key directly when initializing the toolkit:

import { RecallAgentToolkit } from "@recallnet/agent-toolkit/mcp";
 
const toolkit = new RecallAgentToolkit({
  privateKey: "YOUR_PRIVATE_KEY", // Not recommended in production code
  configuration: {
    // Configuration options
  },
});

Never hardcode your private key directly in your source code, especially in public repositories. Use environment variables or secure credential management systems.

Environment variables

The recommended approach for most applications is to use environment variables:

import { RecallAgentToolkit } from "@recallnet/agent-toolkit/mcp";
 
const toolkit = new RecallAgentToolkit({
  privateKey: process.env.RECALL_PRIVATE_KEY,
  configuration: {
    // Configuration options
  },
});

This approach keeps your private key out of your source code and allows for different keys in different environments.

Create & configure a private key

To get started with the Recall Agent Toolkit, you'll need a private key. There are two ways to do this:

Use the Recall CLI's recall account create command.
Use your browser wallet (e.g,. MetaMask), add an account, and then export the private key.

Copy the generated private key and store it securely. This is the only time you will see the full key value. Then, set the key in your environment variables:

.env

# For development (.env file)
RECALL_PRIVATE_KEY=your_private_key

Security best practices

Environment-specific keys

Use different private keys for different environments:

// Load different environment variables based on the environment
const privateKey =
  process.env.NODE_ENV === "production"
    ? process.env.RECALL_PRODUCTION_KEY
    : process.env.RECALL_DEVELOPMENT_KEY;
 
const toolkit = new RecallAgentToolkit({
  privateKey,
  configuration: {
    // Configuration options
  },
});

Restricted permissions

Limit the permissions of your key to only what's necessary:

const toolkit = new RecallAgentToolkit({
  privateKey: process.env.RECALL_PRIVATE_KEY,
  configuration: {
    actions: {
      // Only grant the permissions your application needs
      account: { read: true, write: false },
      bucket: { read: true, write: true },
    },
  },
});

Secure storage

Ensure your environment variables are securely stored:

// Use dotenv to load environment variables from .env file (dev only)
if (process.env.NODE_ENV !== "production") {
  import("dotenv").then((dotenv) => dotenv.config());
}
 
// In production, use environment variables set on the server
const toolkit = new RecallAgentToolkit({
  privateKey: process.env.RECALL_PRIVATE_KEY,
  // Configuration options
});

Keys & client-side code

Never include keys in client-side code! Keep all authentication on the server side:

// ❌ WRONG: Exposing key in frontend code
// client-side.js
const toolkit = new RecallAgentToolkit({
  privateKey: "exposed_key", // This is visible to users!
});
 
// ✅ RIGHT: Keep authentication on the server
// server.js (Node.js, API route, etc.)
const toolkit = new RecallAgentToolkit({
  privateKey: process.env.RECALL_PRIVATE_KEY,
});
 
// client-side.js
// Make API calls to your server, which then uses the toolkit
async function storeData(data) {
  const response = await fetch('/api/store', {
    method: 'POST',
    body: JSON.stringify({ data }),
  });
  return response.json();
}

Authentication for different frameworks

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { RecallAgentToolkit } from "@recallnet/agent-toolkit/mcp";
 
const privateKey = process.env.RECALL_PRIVATE_KEY;
 
if (!privateKey) {
  throw new Error('RECALL_PRIVATE_KEY environment variable not set');
}
 
const toolkit = new RecallAgentToolkit({
  privateKey,
  configuration: {
    actions: {
      bucket: { read: true, write: true },
    },
    context: {
      // Configuration options
    },
  },
});
 
// Connect to MCP transport
const transport = new StdioServerTransport();
toolkit.connect(transport);

Next steps

Learn about bucket monitoring to track your agent's storage
Explore the tools reference for detailed documentation on available tools
Check out MCP integration for using the toolkit with MCP-compatible models
See framework integration guides for integrating with different AI frameworks

If you have questions or need help with authentication, reach out to the Recall team on Discord or GitHub.

Authentication

On this page