🚂 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

1. Click the deploy button above

2. Connect your GitHub account to Railway

3. Add environment variable: LETTA_API_KEY=your_letta_api_key_here

4. Deploy - your MCP server will be live in under 2 minutes!

Your MCP Server URL

https://your-app-name.up.railway.app/mcp

Related MCP server: Redshift MCP Server

⚡ 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

Letta Cloud Setup

1. Sign up: Create account at letta.com

2. Get API key: Visit api.letta.com → Settings → API Keys

3. Create agent: Use the web interface to create your first agent

4. Test connection: Use letta_health_check tool to verify

🛠️ Available Tools (20+ Letta Functions)

🤖 Agent Management

• letta_list_agents - List all agents with pagination and filtering

• letta_create_agent - Create new agents with memory blocks and tools

• letta_get_agent - Get detailed agent information

• letta_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 support

• letta_get_conversation_history - Retrieve chat history with pagination

• letta_export_conversation - Export conversations (markdown, JSON, text)

🧠 Memory Management

• letta_get_memory - View all memory blocks for an agent

• letta_update_memory - Update memory blocks (human, persona, custom)

• letta_create_memory_block - Create custom memory blocks

• letta_search_memory - Search through agent conversation memory

🔧 Tool Management

• letta_list_tools - List all available tools with filtering

• letta_get_agent_tools - View tools attached to specific agents

• letta_attach_tool - Add tools to agents

• letta_detach_tool - Remove tools from agents

📊 Monitoring & Health

• letta_health_check - Verify API connection and service status

• letta_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

💻 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

1. Check Railway logs: View deployment logs in Railway dashboard

2. Test health endpoint: Visit https://your-app.up.railway.app/health

3. Verify MCP endpoint: Test with MCP Inspector

4. Community support: Join Letta Discord

5. 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

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes and add tests

4. Test locally: pytest tests/

5. Commit with clear messages: git commit -m "Add amazing feature"

6. Push to your fork: git push origin feature/amazing-feature

7. 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