Letta MCP server for AI agents

The Letta MCP Server is an implementation of the Model Context Protocol for the Letta API, providing tools to manage agents, memory blocks, and tools within the Letta system. It offers a structured way to create, manage, and interact with AI agents and their associated data.

Installation

To get started with the Letta MCP Server:

# Clone the repository
git clone https://github.com/oculairmedia/Letta-MCP-server.git
cd letta-server

# Install dependencies
npm install

Configuration

Create a .env file in the root directory with the following variables:

LETTA_BASE_URL=your_letta_api_url
LETTA_PASSWORD=your_letta_api_password

You can use the provided .env.example as a template.

Running the Server

The server can be started using one of the following commands:

# Build and start the server
npm run build
npm run start

# Or run in development mode with auto-reload
npm run dev

Features and Capabilities

Agent Management

Agents can be configured with various options:

Model selection (default: 'openai/gpt-4')
Embedding model (default: 'openai/text-embedding-ada-002')
Context window size (default: 16000)
Temperature and token settings
Custom function configurations

Available Operations:

Create new agents
List and filter existing agents
Send messages to agents and receive responses

Memory Block Management

Memory blocks serve different purposes based on their labels:

persona: Define agent personality and behavior
human: Store conversation history and user preferences
system: Store system-level instructions and configurations
custom: User-defined memory blocks for specific use cases

Available Operations:

Create new memory blocks with names, labels, and content
Read and update existing memory blocks
List memory blocks with filtering options
Attach memory blocks to agents with custom labels

Tool Management

Tools extend the capabilities of agents.

Available Operations:

List all available tools with filtering
List tools available for a specific agent
Attach tools to agents
Upload new Python tools with custom implementation

Example Usage

When integrated with Cline, you can use the MCP tools as follows:

Working with Memory Blocks

<!-- Create a memory block -->
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>create_memory_block</tool_name>
<arguments>
{
  "name": "example_block",
  "label": "custom",
  "value": "This is an example memory block.",
  "metadata": {
    "version": "1.0",
    "type": "documentation"
  }
}
</arguments>
</use_mcp_tool>

<!-- List memory blocks with filtering -->
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>list_memory_blocks</tool_name>
<arguments>
{
  "label": "custom",
  "page": 1,
  "pageSize": 10,
  "include_full_content": true
}
</arguments>
</use_mcp_tool>

<!-- Update a memory block -->
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>update_memory_block</tool_name>
<arguments>
{
  "block_id": "block-123",
  "value": "Updated content",
  "metadata": {
    "version": "1.1"
  }
}
</arguments>
</use_mcp_tool>

<!-- Attach block to agent with label -->
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>attach_memory_block</tool_name>
<arguments>
{
  "block_id": "block-123",
  "agent_id": "agent-456",
  "label": "persona"
}
</arguments>
</use_mcp_tool>

Managing Tools

<!-- Upload a new tool -->
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>upload_tool</tool_name>
<arguments>
{
  "name": "weather_tool",
  "description": "Get weather information for a location",
  "source_code": "def get_weather(location):\n    # Tool implementation\n    return {'temp': 72, 'condition': 'sunny'}",
  "category": "utilities",
  "agent_id": "agent-456"  // Optional: automatically attach to agent
}
</arguments>
</use_mcp_tool>

<!-- List tools with filtering -->
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>list_tools</tool_name>
<arguments>
{
  "filter": "weather",
  "page": 1,
  "pageSize": 10
}
</arguments>
</use_mcp_tool>

Response Format

All MCP tools return responses in a consistent format:

{
  "success": boolean,
  "message": string,           // Success/error message
  "error"?: string,           // Present only on error
  "details"?: any,            // Additional error details if available
  // Tool-specific data...
}

Error Handling

The server handles various error scenarios:

Invalid arguments or missing parameters
API authentication failures
Resource not found errors
Rate limiting and quota errors
Network connectivity issues

Each error response includes detailed information to help troubleshoot issues.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.