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

# 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):

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

   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:

   railway up

4. Get your deployment URL:

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

{
  "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:

{
  "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)

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

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

Logs

View logs in Railway:

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