The Letta MCP Server provides comprehensive tools for agent management, memory operations, and tool integration within the Letta system.
Agent Management: Create, list, prompt, modify, delete, clone, and bulk delete agents with specific configurations
Memory Management: Create, list, read, update, and attach memory blocks to agents
Tool Management: List, attach (individually or in bulk), and upload tools for agents
Additional Features: Manage models (LLM and embedding), archive passages, other MCP servers, and import/export agent configurations
Deployment: Run locally with Node.js or Docker, configurable via
mcp_settings.json
Uses .env files for configuration, allowing storage of Letta API credentials and endpoints securely outside of the codebase.
Repository hosting for the Letta MCP server, enabling version control, contribution workflows, and distribution of the server code.
Provides package management for the Letta MCP server, managing dependencies and offering scripts for building and running the server.
Used as the implementation language for the Letta MCP server, with build scripts to compile TypeScript code before execution.
Letta MCP Server
A Model Context Protocol (MCP) server that provides comprehensive tools for agent management, memory operations, and integration with the Letta system. This server implements the full MCP specification including tools, prompts, and resources, with enhanced descriptions, output schemas, and behavioral annotations.
Features
- 🤖 Agent Management - Create, modify, clone, and manage Letta agents
- 🧠 Memory Operations - Handle memory blocks and passages
- 🔧 Tool Integration - Attach and manage tools for agents with full MCP support
- 💬 Prompts - Interactive wizards and assistants for common workflows
- 📚 Resources - Access system information, documentation, and agent data
- 🌐 Multiple Transports - HTTP, SSE, and stdio support
- 🔗 MCP Server Integration - Integrate with other MCP servers
- 📊 Enhanced Metadata - Output schemas and behavioral annotations for all tools
- 📦 Docker Support - Easy deployment with Docker
Environment Configuration
Create a .env
file with the following variables:
Installation
Install from npm
Use with Claude Desktop
After installing globally, add to your Claude Desktop configuration:
Quick Start with npm
Quick Setup
Option 1: Run from source
Option 2: Run with Docker
Using the prebuilt image from GitHub Container Registry
Available tags:
latest
- Latest stable release2.0.1
,2.0
,2
- Specific version tagsmaster
- Latest master branch build
Using Docker Compose
Building from source
Option 3: Run with stdio for local MCP
Architecture
See the Architecture Documentation for detailed system diagrams and component relationships.
MCP Protocol Support
This server implements the full MCP specification with all three capabilities:
🔧 Tools
All tools include:
- Enhanced Descriptions: Detailed explanations with use cases and best practices
- Output Schemas: Structured response definitions for predictable outputs
- Behavioral Annotations: Hints about tool behavior (readOnly, costLevel, executionTime, etc.)
💬 Prompts
Interactive prompts for common workflows:
letta_agent_wizard
- Guided agent creation with memory and tool setupletta_memory_optimizer
- Analyze and optimize agent memory usageletta_debug_assistant
- Troubleshoot agent issuesletta_tool_config
- Discover, attach, create, or audit toolsletta_migration
- Export, import, upgrade, or clone agents
📚 Resources
Access system information and documentation:
letta://system/status
- System health and version infoletta://system/models
- Available LLM and embedding modelsletta://agents/list
- Overview of all agentsletta://tools/all/docs
- Complete tool documentation with examplesletta://docs/mcp-integration
- Integration guideletta://docs/api-reference
- API quick reference
Resource templates for dynamic content:
letta://agents/{agent_id}/config
- Agent configurationletta://agents/{agent_id}/memory/{block_id}
- Memory block contentletta://tools/{tool_name}/docs
- Individual tool documentation
Available Tools
Agent Management
Tool | Description | Annotations |
---|---|---|
create_agent | Create a new Letta agent | 💰 Medium cost, ⚡ Fast |
list_agents | List all available agents | 👁️ Read-only, 💰 Low cost |
prompt_agent | Send a message to an agent | 💰 High cost, ⏱️ Variable time, 🔒 Rate limited |
retrieve_agent | Get agent details by ID | 👁️ Read-only, ⚡ Fast |
get_agent_summary | Get agent summary information | 👁️ Read-only, ⚡ Fast |
modify_agent | Update an existing agent | ✏️ Modifies state, ⚡ Fast |
delete_agent | Delete an agent | ⚠️ Dangerous, 🗑️ Permanent |
clone_agent | Clone an existing agent | 💰 Medium cost, ⏱️ Medium time |
bulk_delete_agents | Delete multiple agents | ⚠️ Dangerous, 📦 Bulk operation |
export_agent | Export agent configuration and memory | 👁️ Read-only, ⚡ Fast, 📦 Full backup |
import_agent | Import agent from backup | 💰 High cost, ⏱️ Slow, ✏️ Creates state |
Memory Management
Tool | Description | Annotations |
---|---|---|
list_memory_blocks | List all memory blocks | 👁️ Read-only, ⚡ Fast |
create_memory_block | Create a new memory block | ✏️ Creates state, ⚡ Fast |
read_memory_block | Read a memory block | 👁️ Read-only, ⚡ Fast |
update_memory_block | Update a memory block | ✏️ Modifies state, ⚡ Fast |
attach_memory_block | Attach memory to an agent | ✏️ Links resources, ⚡ Fast |
Passage Management
Tool | Description | Annotations |
---|---|---|
list_passages | Search archival memory | 👁️ Read-only, ⚡ Fast |
create_passage | Create archival memory | 💰 Medium cost (embeddings), ⚡ Fast |
modify_passage | Update archival memory | 💰 Medium cost (re-embedding), ⚡ Fast |
delete_passage | Delete archival memory | 🗑️ Permanent, ⚡ Fast |
Tool Management
Tool | Description | Annotations |
---|---|---|
list_agent_tools | List tools for an agent | 👁️ Read-only, ⚡ Fast |
attach_tool | Attach tools to an agent | ✏️ Modifies capabilities, ⚡ Fast |
upload_tool | Upload a custom tool | 🔒 Security: Executes code, ⚡ Fast |
bulk_attach_tool_to_agents | Attach tool to multiple agents | 📦 Bulk operation, ⏱️ Slow |
Model Management
Tool | Description | Annotations |
---|---|---|
list_llm_models | List available LLM models | 👁️ Read-only, ⚡ Fast |
list_embedding_models | List available embedding models | 👁️ Read-only, ⚡ Fast |
MCP Integration
Tool | Description | Annotations |
---|---|---|
list_mcp_servers | List configured MCP servers | 👁️ Read-only, ⚡ Fast |
list_mcp_tools_by_server | List tools from an MCP server | 👁️ Read-only, ⚡ Fast |
add_mcp_tool_to_letta | Import MCP tool to Letta | ✏️ Creates tool, ⚡ Fast |
Prompt Tools
Tool | Description | Annotations |
---|---|---|
list_prompts | List available prompt templates | 👁️ Read-only, ⚡ Fast |
use_prompt | Execute a prompt template | 💰 Variable cost, ⏱️ Variable time |
Directory Structure
src/index.js
- Main entry pointsrc/core/
- Core server functionalitysrc/handlers/
- Prompt and resource handlerssrc/examples/
- Example prompts and resourcessrc/tools/
- Tool implementations organized by category:agents/
- Agent management toolsmemory/
- Memory block toolspassages/
- Passage management toolstools/
- Tool attachment and managementmcp/
- MCP server integration toolsmodels/
- Model listing toolsenhanced-descriptions.js
- Detailed tool descriptionsoutput-schemas.js
- Structured output definitionsannotations.js
- Behavioral hints
src/transports/
- Server transport implementations
Transport Protocols
The server supports three transport protocols:
- HTTP (Recommended) - Streamable HTTP transport with full duplex communication
- Endpoint:
http://your-server:3001/mcp
- Best for production use and remote connections
- Supports health checks at
/health
- Endpoint:
- SSE (Server-Sent Events) - Real-time event streaming
- Endpoint:
http://your-server:3001/sse
- Good for unidirectional server-to-client updates
- Endpoint:
- stdio - Standard input/output
- Direct process communication
- Best for local development and Claude integration
Configuration with MCP Settings
Add the server to your mcp_settings.json:
For remote instances with HTTP transport (recommended):
Docker Operations
Troubleshooting
Common Issues
- Connection refused errors
- Ensure the server is running and accessible
- Check firewall settings for port 3001
- Verify the correct transport protocol is being used
- Authentication failures
- Verify LETTA_BASE_URL includes
/v1
suffix - Check LETTA_PASSWORD is correct
- Ensure environment variables are loaded
- Verify LETTA_BASE_URL includes
- Tool execution timeouts
- Increase timeout values in MCP configuration
- Check network latency for remote connections
- Consider using HTTP transport for better reliability
Health Check
The HTTP transport provides a health endpoint:
Response:
Development
Testing
Contributing
We welcome contributions! Please see our Contributing Guide for details on:
- Development setup
- Code style and standards
- Adding new tools
- Testing requirements
- Pull request process
Security
For security vulnerabilities, please see our Security Policy.
License
MIT License - see LICENSE file for details
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
An MCP server implementation that enables interaction with the Letta API for managing agents, memory blocks, and tools in the Letta system.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Linear project management systems, allowing users to retrieve, create, and update issues, projects, and teams through natural language.Last updated -421,070101MIT License
- AsecurityFlicenseAqualityAn MCP server that enables LLMs to interact with Agent-to-Agent (A2A) protocol compatible agents, allowing for sending messages, tracking tasks, and receiving streaming responses.Last updated -525
- AsecurityAlicenseAqualityThe Atla MCP Server provides a standardized interface for LLMs to interact with the Atla API for state-of-the-art LLMJ evaluation.Last updated -216MIT License
- AsecurityAlicenseAqualityA meta-MCP server that manages and aggregates other MCP servers, enabling LLMs to dynamically extend their own capabilities by searching for, adding, and configuring tool servers.Last updated -1658AGPL 3.0