iflow-mcp_letta-mcp-server-railway 1.0.0
Railway HTTP deployment edition of Letta MCP Server - connects AI clients to Letta.ai agents
Requires Python: >=3.10
Keywords: letta, mcp, model-context-protocol, ai, agents, llm, railway, http-deployment, streamable-http, claude, openai, fastmcp, memgpt, universal, interoperability

# 🚂 Letta MCP Server Railway Edition

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/lrR1XO?referralCode=ascend)
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Railway Compatible](https://img.shields.io/badge/Railway-Compatible-purple)](https://railway.app)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org)
[![MCP](https://img.shields.io/badge/MCP-2.0-green)](https://modelcontextprotocol.io)

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

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/lrR1XO?referralCode=ascend)

### Prerequisites
- **Letta API key** from [api.letta.com](https://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
```

---

## ⚡ 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`

```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:

```bash
npx @modelcontextprotocol/inspector https://your-app.up.railway.app/mcp
```

### GitHub Copilot & VS Code
```json
{
  "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
1. **Sign up**: Create account at [letta.com](https://letta.com)
2. **Get API key**: Visit [api.letta.com](https://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
```python
# 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
```bash
# 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
```bash
# 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
```bash
# Run tests
pytest tests/

# Format code
black src/ tests/

# Type checking  
mypy src/

# Lint
ruff check src/
```

---

## 🔍 Troubleshooting

### Common Issues

#### 1. "Connection refused" error
```bash
# 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  
```bash
# Test your Letta API key directly
curl -H "Authorization: Bearer your_api_key" https://api.letta.com/v1/agents
```

#### 3. "Timeout" errors
```bash
# 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](https://discord.gg/letta)
5. **Report issues**: [GitHub Issues](https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway/issues)

---

## 🚀 Production Deployment

### Railway Deployment Best Practices

#### Environment Management
```bash
# 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
```toml
# railway.toml - Production settings
[build]
builder = "DOCKERFILE"

[deploy] 
restartPolicyType = "ON_FAILURE"

[[deploy.environmentVariables]]
name = "PORT"
value = "8000"
```

---

## 📖 Resources

### Documentation
- **[Letta Documentation](https://docs.letta.com)** - Complete Letta platform guide
- **[MCP Specification](https://modelcontextprotocol.io)** - Model Context Protocol standard
- **[Railway Documentation](https://docs.railway.app)** - Railway platform guide
- **[FastMCP Documentation](https://github.com/jlowin/fastmcp)** - HTTP transport framework

### Community & Support  
- **[Letta Discord](https://discord.gg/letta)** - Active community support
- **[MCP Community](https://github.com/modelcontextprotocol)** - Protocol development
- **[Railway Community](https://railway.app/discord)** - Deployment support
- **[GitHub Issues](https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway/issues)** - Bug reports and features

### Examples & Tutorials
- **[Letta Agent Examples](https://docs.letta.com/examples)** - Sample agent configurations
- **[MCP Client Integration](https://modelcontextprotocol.io/clients)** - Client setup guides
- **[Railway Templates](https://railway.app/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
```bash
# 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](LICENSE) for details.

---

## 🙏 Acknowledgments

Built with ❤️ by the community for seamless AI agent deployment.

**Special Thanks**:
- **[Letta.ai](https://letta.com)** for revolutionary stateful agents
- **[Railway](https://railway.app)** for exceptional deployment platform  
- **[Anthropic](https://anthropic.com)** for MCP specification leadership
- **[FastMCP](https://github.com/jlowin/fastmcp)** for HTTP transport framework
- **All contributors** making this project possible

---

<p align="center">
  <strong>🚂 Deploy Letta agents to the cloud in 30 seconds - Railway makes it effortless.</strong>
</p>

<p align="center">
  <a href="https://railway.app/new/template?template=https://github.com/SNYCFIRE-CORE/letta-mcp-server-railway">
    <img src="https://railway.app/button.svg" alt="Deploy on Railway">
  </a>
</p>