# EST Call Agent - FastMCP Cloud Server

A URL/HTTP-based MCP (Model Context Protocol) server for the AI Phone Agent Platform. This server can be deployed to Railway, Render, Fly.io, or any cloud platform and allows AI assistants (like Claude in Cursor) to interact with your call campaigns via HTTP instead of stdio.

## 🌟 Features

- **HTTP/URL-based MCP server** using FastMCP
- **Cloud-ready deployment** with Docker support
- **Organization-scoped authentication** via API keys
- **REST API integration** - calls python-server-est API instead of direct imports
- **No dependencies on main application code** - fully independent deployment

## 🏗️ Architecture

```
Cursor/Claude Desktop
       ↓ (HTTP/HTTPS)
FastMCP Server (this project)
       ↓ (REST API calls)
python-server-est API (Railway)
       ↓
Twilio + OpenAI
```

## 📦 Installation

### Local Development

```bash
# Clone or navigate to project
cd python-mcp-est

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
nano .env
```

### Environment Variables

Required environment variables (see `.env.example`):

```env
# Organization Authentication
ORGANIZATION_API_KEY=your_api_key_from_org_settings
ORGANIZATION_ID=your_organization_uuid

# API Configuration
API_BASE_URL=https://python-server-est-production.up.railway.app

# Supabase (for API key validation)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key
```

## 🚀 Deployment

### Railway Deployment

1. **Create new Railway project:**
   ```bash
   railway login
   railway init
   ```

2. **Set environment variables in Railway dashboard:**
   - `ORGANIZATION_API_KEY`
   - `ORGANIZATION_ID`
   - `API_BASE_URL`
   - `SUPABASE_URL`
   - `SUPABASE_SERVICE_KEY`

3. **Deploy:**
   ```bash
   railway up
   ```

4. **Get your deployment URL:**
   ```bash
   railway status
   ```
   Example: `https://python-mcp-est-production.up.railway.app`


## 🔌 Connecting to Cursor/Claude Desktop

### Cursor Configuration

Edit your Cursor MCP config file (usually `~/.cursor/mcp.json` or workspace `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "est-call-agent": {
      "url": "https://your-mcp-server.railway.app/mcp",
      "headers": {
        "X-API-Key": "your_organization_api_key"
      }
    }
  }
}
```

### Claude Desktop Configuration

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:

```json
{
  "mcpServers": {
    "est-call-agent": {
      "url": "https://your-mcp-server.railway.app/mcp",
      "headers": {
        "X-API-Key": "your_organization_api_key"
      }
    }
  }
}
```

## 🛠️ Available Tools

### 1. `start_campaign_call_scheduled`
Schedule a single outbound call for a specific client at a given time.

**Parameters:**
- `campaign_id` (string): Campaign UUID
- `phone_number` (string): Client number in E.164 format
- `scheduled_time` (string): ISO 8601 timestamp (campaign timezone respected)
- `first_name`, `last_name`, `company`, `email`, `extrainfo` (strings, optional): Metadata stored as contact custom data

**Returns:** Call ID, scheduled timestamps, and subscription usage details from the API.

### 2. `list_voice_agents`
Lists all voice agent campaigns for the authenticated organization.

**Returns:** Array of campaign objects with `campaign_id`, `name`, `status`, `campaign_type`, `created_at`, and `is_active` fields.

### 3. `get_call_data_by_id`
Retrieves a single call record from Supabase.

**Parameters:**
- `call_id` (string): Supabase call identifier

**Returns:** Full call JSON when found.

### 4. `list_recent_calls`
Lists the most recent calls for the organization.

**Parameters:**
- `limit` (integer, optional): Number of calls to return (default 25, max 200)

**Returns:** Array of call records ordered by newest first.

### 5. `get_twilio_number`
Returns the Twilio phone number configured for the organization.

**Returns:** `twilio_phone_number` string.

### 6. `list_inbound_clients`
Lists inbound client records.

**Parameters:**
- `limit` (integer, optional): Number of records to return (default 25, max 200)

**Returns:** Array of inbound client objects ordered by creation date.

### 7. `get_webhook_url`
Returns the webhook URL configured for the organization.

**Returns:** `webhook_url` string.

### 8. `get_organisation_members`
Returns organization members with their name, email, and last login timestamp.

**Returns:** Array of member objects: `{ "full_name", "email", "last_login_at" }`.

## 🧪 Testing

### Local Testing (HTTP mode)

```bash
# Run server
python cloud_mcp_server.py

# Test with curl
curl http://localhost:8000/mcp
```

## 📊 Monitoring

### Health Check

The server includes a health check endpoint:

```bash
curl https://your-mcp-server.railway.app/health
```

### Logs

View logs in Railway:
```bash
railway logs
```

## 🔒 Security

- **API Key Authentication**: All requests require a valid organization API key
- **Organization Scoping**: All data is automatically filtered to the authenticated organization
- **HTTPS Required**: Use HTTPS in production (automatically provided by Railway/Render/Fly)
- **Environment Variables**: Never commit `.env` file or expose secrets

## 🐛 Troubleshooting

### Connection Issues

1. **Check deployment URL**: Ensure the URL in your MCP config matches your deployment
2. **Verify API key**: Check that `ORGANIZATION_API_KEY` is set correctly in both server and client
3. **Check logs**: Review Railway/Render logs for error messages

### API Errors

1. **Validate API base URL**: Ensure `API_BASE_URL` points to python-server-est
2. **Check organization ID**: Verify `ORGANIZATION_ID` is correct
3. **Review API timeouts**: Increase `API_TIMEOUT` if needed

### Authentication Failures

1. **Regenerate API key**: Generate a new key in organization settings
2. **Verify Supabase config**: Check `SUPABASE_URL` and `SUPABASE_SERVICE_KEY`
3. **Check database**: Verify API key exists in `organization_service_credentials` table

## 📝 Development

### Project Structure

```
python-mcp-est/
├── cloud_mcp_server.py   # FastMCP server implementation
├── mcp_handlers.py       # Tool handlers (calls REST API)
├── requirements.txt      # Python dependencies
├── Dockerfile           # Container definition
├── railway.toml         # Railway configuration
├── .env.example         # Environment template
└── README.md           # This file
```

### Adding New Tools

1. Add handler function in `mcp_handlers.py`
2. Add tool definition in `cloud_mcp_server.py` using `@mcp.tool()` decorator
3. Update this README with tool documentation

## 📄 License

Same as the parent EST Call Agent Platform project.

## 🆘 Support

For issues or questions:
1. Check the logs first
2. Review Railway/Render deployment status
3. Verify all environment variables are set correctly
4. Check python-server-est API is responding

## 🔗 Related Projects

- **python-server-est**: Main API server for outbound calls
- **phone-agent-platform-EST**: Next.js frontend application