Soab42/mcp-server

Telnyx AI → MCP (fastmcp) → Google + Postgres

This project gives you:

• An MCP server exposing tools to create leads (Postgres), schedule meetings (Google Calendar), and send emails (Gmail).
• A FastAPI webhook (POST /webhooks/telnyx-ai) that processes Telnyx AI call events end-to-end.

Architecture

Telnyx AI → (Webhook) FastAPI →

1. Postgres: insert lead
2. Google Calendar: create event (optional)
3. Gmail: send confirmation (optional)

All 3 actions are also available as MCP tools via fastmcp.

File Structure

• main.py: The main entry point for the application. It initializes the FastAPI and FastMCP servers, and registers the webhook and MCP tools.
• db.py: Handles database connections and operations.
• google_client.py: Manages interactions with Google Calendar and Gmail APIs.
• mcp_tools.py: Contains all the MCP tool definitions.
• telnyx_handler.py: Handles the incoming Telnyx AI webhook.
• models.py: Defines the Pydantic models for the Telnyx AI webhook payload.

Prereqs

• Python 3.11+
• Postgres database
• Google Workspace recommended (service account with domain-wide delegation)
• Telnyx AI Assistant configured to hit your public webhook URL

Quick Start

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL="postgresql+psycopg2://user:pass@host:5432/db"
export GOOGLE_SERVICE_ACCOUNT_INFO='{"type": "service_account", ... }'
export GOOGLE_IMPERSONATE_SUBJECT="support@businessvoicepro.com"
export GMAIL_SENDER="support@businessvoicepro.com"
export CALLER_INFO_DATABASE_URL="postgresql+psycopg2://user:pass@host:5432/caller_db"
uvicorn main:app --host 0.0.0.0 --port 8080

Your webhook endpoint is now https://<your-domain-or-ip>:8080/webhooks/telnyx-ai.

Without service accounts

Put credentials.json (OAuth client) beside the app, run a one-time auth flow locally to generate token.json, then deploy both. Set:

export GOOGLE_CLIENT_SECRET_PATH=credentials.json
export GOOGLE_TOKEN_PATH=token.json
export GMAIL_SENDER=support@businessvoicepro.com

Telnyx AI Webhook Payload (example)

{
  "call_id": "abc123",
  "caller_number": "+15551234567",
  "caller_name": "Alex Buyer",
  "caller_email": "alex@example.com",
  "transcript": "I want to book a showing next Tuesday at 3pm",
  "meeting_summary": "Buyer Consultation",
  "meeting_description": "Inbound from IVR",
  "meeting_start_iso": "2025-10-14T15:00:00Z",
  "meeting_duration_min": 30,
  "attendees": ["agent@yourbrokerage.com"]
}

MCP Tools

• mcp_create_lead(name, phone, email, notes) → {status, lead_id}
• mcp_schedule_meeting(summary, description, start_iso, end_iso, attendees, calendar_id) → {status, event}
• mcp_send_email(to, subject, body_text, reply_to) → {status}
• mcp_process_telnyx_payload(payload_json) → End-to-end processing.
• mcp_check_calendar(start_iso, end_iso, calendar_id) → {status, message}
• mcp_get_caller_info(phone_number) → {status, caller_info}

MCP Inspector

To inspect and test the available MCP tools, run the following command:

uv run fastmcp dev main.py

MCP Demo Data

mcp_process_telnyx_payload

{
  "payload_json": "{\"call_id\": \"xyz789\", \"caller_number\": \"+15559876543\", \"caller_name\": \"Dana Developer\", \"caller_email\": \"dana@example.com\", \"transcript\": \"Hi, I'd like to check if there is a meeting slot available next Wednesday at 10am.\", \"meeting_summary\": \"Availability Check\", \"meeting_description\": \"Checking for an open slot.\", \"meeting_start_iso\": \"2025-10-22T10:00:00Z\", \"meeting_duration_min\": 15, \"attendees\": [\"agent@yourbrokerage.com\"]}"
}

mcp_create_lead

{
  "name": "John Doe",
  "phone": "+15551112222",
  "email": "john.doe@example.com",
  "notes": "Interested in a demo."
}

mcp_schedule_meeting

{
  "summary": "Project Kick-off",
  "description": "Initial meeting to discuss project goals.",
  "start_iso": "2025-11-01T14:00:00Z",
  "end_iso": "2025-11-01T15:00:00Z",
  "attendees": ["jane.doe@example.com", "john.doe@example.com"]
}

mcp_send_email

{
  "to": ["recipient@example.com"],
  "subject": "Hello from MCP",
  "body_text": "This is a test email from the MCP server."
}

mcp_check_calendar

{
  "start_iso": "2025-10-29T10:00:00Z",
  "end_iso": "2025-10-29T11:00:00Z"
}

MCP Tool Call Logs

The MCP tool calls are logged to the database in the mcp_tool_logs table. You can view a live feed of these logs by navigating to the /logs-ui endpoint in your web browser.

Database

On first run, the table leads is created automatically. Customize schema in db.py.

Deployment Notes

• VPS: run behind NGINX with HTTPS (Let’s Encrypt). Example systemd unit:

[Unit]
Description=Telnyx MCP API
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/opt/telnyx-mcp
Environment="DATABASE_URL=postgresql+psycopg2://..."
Environment="GOOGLE_SERVICE_ACCOUNT_INFO=..."
Environment="GOOGLE_IMPERSONATE_SUBJECT=support@businessvoicepro.com"
Environment="GMAIL_SENDER=support@businessvoicepro.com"
ExecStart=/opt/telnyx-mcp/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8080
Restart=always

[Install]
WantedBy=multi-user.target

• Security: Add a Telnyx signature secret and verify HMAC on incoming requests; restrict CORS; store secrets in a vault.

Telnyx Signature Verification (pseudo)

Verify Telnyx-Signature-Ed25519 headers. See Telnyx docs and add verification before processing.

Troubleshooting

• Google clients not configured → Ensure either service account vars or OAuth files are present.
• 403 on Gmail send → Your Workspace admin must allow domain-wide delegation, or use an OAuth user token with send scope.