🚂 Letta MCP Server Railway Edition
Cloud-optimized HTTP transport edition of Letta MCP Server - Deploy to Railway in 30 seconds.
Universal MCP server connecting any AI client to Letta.ai's powerful stateful agents via streamable HTTP for seamless cloud deployment.
🚀 Quick Deploy to Railway
Prerequisites
- Letta API key from api.letta.com (free tier available)
- Railway account (free tier includes 500 hours/month)
One-Click Deployment
- Click the deploy button above
- Connect your GitHub account to Railway
- Add environment variable:
LETTA_API_KEY=your_letta_api_key_here - Deploy - your MCP server will be live in under 2 minutes!
Your MCP Server URL
https://your-app-name.up.railway.app/mcp
⚡ Integration with AI Clients
Claude Desktop (ADE Integration)
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"letta-railway": {
"url": "https://your-app.up.railway.app/mcp",
"transport": "streamable_http",
"timeout": 300,
"headers": {
"User-Agent": "Claude-Desktop-MCP/1.0"
}
}
}
}
MCP Inspector Testing
Test your deployment with the MCP Inspector:
npx @modelcontextprotocol/inspector https://your-app.up.railway.app/mcp
GitHub Copilot & VS Code
{
"mcp.servers": {
"letta-railway": {
"transport": "streamable_http",
"url": "https://your-app.up.railway.app/mcp"
}
}
}
Other MCP Clients
- Cursor: Add server to MCP configuration
- Replit: Use MCP-compatible endpoint configuration
- Sourcegraph Cody: Configure via OpenCtx bridge
- Any MCP Client: Use streamable HTTP transport
🔧 Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
LETTA_API_KEY | ✅ Yes | - | Your Letta API key from api.letta.com |
LETTA_BASE_URL | No | https://api.letta.com | Letta API endpoint (for self-hosted) |
PORT | No | 8000 | Railway auto-assigns this |
LETTA_TIMEOUT | No | 60 | Request timeout in seconds |
LETTA_MAX_RETRIES | No | 3 | Max retry attempts for failed requests |
Letta Cloud Setup
- Sign up: Create account at letta.com
- Get API key: Visit api.letta.com → Settings → API Keys
- Create agent: Use the web interface to create your first agent
- Test connection: Use
letta_health_checktool to verify
🛠️ Available Tools (20+ Letta Functions)
🤖 Agent Management
letta_list_agents- List all agents with pagination and filteringletta_create_agent- Create new agents with memory blocks and toolsletta_get_agent- Get detailed agent informationletta_update_agent- Update agent configuration (name, description, model)letta_delete_agent- Safely delete agents with confirmation
💬 Conversations
letta_send_message- Send messages to agents with streaming supportletta_get_conversation_history- Retrieve chat history with paginationletta_export_conversation- Export conversations (markdown, JSON, text)
🧠 Memory Management
letta_get_memory- View all memory blocks for an agentletta_update_memory- Update memory blocks (human, persona, custom)letta_create_memory_block- Create custom memory blocksletta_search_memory- Search through agent conversation memory
🔧 Tool Management
letta_list_tools- List all available tools with filteringletta_get_agent_tools- View tools attached to specific agentsletta_attach_tool- Add tools to agentsletta_detach_tool- Remove tools from agents
📊 Monitoring & Health
letta_health_check- Verify API connection and service statusletta_get_usage_stats- Get usage statistics and analytics
🏗️ Technical Architecture
Railway-Optimized Features
- Streamable HTTP Transport: Optimized for cloud deployment vs stdio
- Connection Pooling: Maintains persistent connections for performance
- Auto-scaling: Railway automatically scales based on demand
- Zero-downtime Deploys: Hot reloading without connection loss
- Built-in Monitoring: Railway dashboard shows metrics and logs
Performance Optimizations
# Optimized for Railway cloud environment
- HTTP keep-alive connections
- Request/response compression
- Intelligent retry logic with backoff
- Memory-efficient JSON streaming
- Automatic connection pool management
Transport Comparison
| Feature | stdio (local) | streamable-http (Railway) |
|---|---|---|
| Cloud deployment | ❌ No | ✅ Yes |
| Load balancing | ❌ No | ✅ Auto |
| Horizontal scaling | ❌ No | ✅ Yes |
| Health monitoring | ❌ Limited | ✅ Full |
| Zero-downtime deploys | ❌ No | ✅ Yes |
💻 Local Development
Quick Local Setup
# Clone the repository
git clone https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway.git
cd letta-mcp-server-railway
# Install dependencies
pip install -e .
# Set environment variables
export LETTA_API_KEY=your_api_key_here
# Run locally
python -m letta_mcp_server_railway.server
Local Testing
# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/mcp
# Or use curl
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
Development Commands
# Run tests
pytest tests/
# Format code
black src/ tests/
# Type checking
mypy src/
# Lint
ruff check src/
🔍 Troubleshooting
Common Issues
1. "Connection refused" error
# Check if your Railway app is running
curl https://your-app.up.railway.app/health
# Verify environment variables in Railway dashboard
# Ensure LETTA_API_KEY is set correctly
2. "Invalid API key" error
# Test your Letta API key directly
curl -H "Authorization: Bearer your_api_key" https://api.letta.com/v1/agents
3. "Timeout" errors
# Increase timeout in your MCP client configuration
{
"mcpServers": {
"letta-railway": {
"url": "https://your-app.up.railway.app/mcp",
"transport": "streamable_http",
"timeout": 300 // Increase to 5 minutes
}
}
}
4. Claude Desktop not connecting
- Restart Claude Desktop after configuration changes
- Check configuration file syntax with a JSON validator
- Verify the URL is accessible from your browser
Getting Help
- Check Railway logs: View deployment logs in Railway dashboard
- Test health endpoint: Visit
https://your-app.up.railway.app/health - Verify MCP endpoint: Test with MCP Inspector
- Community support: Join Letta Discord
- Report issues: GitHub Issues
🚀 Production Deployment
Railway Deployment Best Practices
Environment Management
# Production environment variables
LETTA_API_KEY=your_production_api_key
LETTA_BASE_URL=https://api.letta.com
PORT=8000 # Railway manages this automatically
LETTA_TIMEOUT=300
LETTA_MAX_RETRIES=5
Health Monitoring
Railway provides built-in monitoring, but you can also:
- Set up custom health checks
- Monitor response times and error rates
- Configure alerts for downtime
Scaling Configuration
# railway.toml - Production settings
[build]
builder = "DOCKERFILE"
[deploy]
restartPolicyType = "ON_FAILURE"
[[deploy.environmentVariables]]
name = "PORT"
value = "8000"
📖 Resources
Documentation
- Letta Documentation - Complete Letta platform guide
- MCP Specification - Model Context Protocol standard
- Railway Documentation - Railway platform guide
- FastMCP Documentation - HTTP transport framework
Community & Support
- Letta Discord - Active community support
- MCP Community - Protocol development
- Railway Community - Deployment support
- GitHub Issues - Bug reports and features
Examples & Tutorials
- Letta Agent Examples - Sample agent configurations
- MCP Client Integration - Client setup guides
- Railway Templates - Deployment templates
🤝 Contributing
We welcome contributions to make Letta MCP Server Railway even better!
Quick Contribution Guide
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Test locally:
pytest tests/ - Commit with clear messages:
git commit -m "Add amazing feature" - Push to your fork:
git push origin feature/amazing-feature - Submit a Pull Request
Development Setup
# Fork and clone your fork
git clone https://github.com/YOUR_USERNAME/letta-mcp-server-railway.git
cd letta-mcp-server-railway
# Install development dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
# Run tests
pytest tests/ -v
Areas We Need Help
- 📖 Documentation improvements
- 🧪 Additional test coverage
- 🔧 Railway deployment optimizations
- 🌐 Multi-language client examples
- 🐛 Bug fixes and performance improvements
📜 License
MIT License - see LICENSE for details.
🙏 Acknowledgments
Built with ❤️ by the community for seamless AI agent deployment.
Special Thanks:
- Letta.ai for revolutionary stateful agents
- Railway for exceptional deployment platform
- Anthropic for MCP specification leadership
- FastMCP for HTTP transport framework
- All contributors making this project possible
🚂 Deploy Letta agents to the cloud in 30 seconds - Railway makes it effortless.