--- title: "AI Platform Copilot & Model Context Protocol (MCP)" description: "Documentation for Platform Copilot (MCP)" --- ## Table of Contents 1. [Overview & Architecture](#1-overview--architecture) 2. [Commercial & Operational Value](#2-commercial--operational-value) 3. [User Experience & Chat Interface](#3-user-experience--chat-interface) 4. [Master System Prompt & Personalization](#4-master-system-prompt--personalization) 5. [Model Context Protocol (MCP) Integration](#5-model-context-protocol-mcp-integration) 6. [Tool Execution & Telephony Capabilities](#6-tool-execution--telephony-capabilities) 7. [Security, RBAC & Multi-Tenant Isolation](#7-security-rbac--multi-tenant-isolation) 8. [CLI Copilot Assistant (`ring2all-copilot`)](#8-cli-copilot-assistant-ring2all-copilot) 9. [Troubleshooting & Verification](#9-troubleshooting--verification) --- ## 1. Overview & Architecture The **SoftSwitch Platform Copilot** is a native, context-aware artificial intelligence assistant embedded into the web portal, NOC operations console, and terminal CLI. Built on Anthropic's open **Model Context Protocol (MCP)**, the Copilot bridges natural language reasoning with real-time telephony control planes (Telephony Event Socket (ESL) and Kamailio binrpc). Unlike generic chatbots, the Platform Copilot executes read and write operations against the live platform—querying extensions, diagnosing call quality, provisioning IVR flows, analyzing CDR patterns, and checking firewall registrations in real time. ``` ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ AI Platform Copilot Architecture │ ├────────────────────────────────────────────────────────────────────────────────────────┤ │ │ │ Web UI Chat Widget CLI Assistant User Portal Softphone │ │ [💬 Copilot Modal] [💻 ring2all-copilot] [🎙️ Realtime Subtitles] │ │ │ │ │ │ │ └───────────────────────┬───────┴───────────────────────────────┘ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ │ │ SoftSwitch API Backend (Fastify 5) │ │ │ │ │ │ │ │ 1. Master System Prompt Engine (Injects platform taxonomy & guidelines) │ │ │ │ 2. Dynamic Tool Filtering (Applies user profile's MCP Tool Role permissions) │ │ │ │ 3. Model Gateway (OpenAI / Anthropic / Local Ollama / vLLM streaming) │ │ │ └──────────────────────────────────────┬──────────────────────────────────────────┘ │ │ │ │ │ ▼ Model Context Protocol (MCP Tools) │ │ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ │ │ MCP Tool Execution Engine │ │ │ │ │ │ │ │ ├─ Database Operations: PostgreSQL (Kysely with strict tenant/domain isolation)│ │ │ │ ├─ Media & Dialplan: Telephony Event Socket Layer (ESL API/bgapi) │ │ │ │ ├─ Perimeter & SIP: Kamailio binrpc (kamcmd dispatcher, drouting, siptrace) │ │ │ │ └─ Diagnostic & Telemetry: RTPEngine MOS metrics & System Cleanup Service │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Commercial & Operational Value - **Drastic Reduction in Tier 1/2 Support Tickets**: Administrators can ask natural language questions such as *"Why is extension 1004 unable to register?"* or *"Summarize today's dropped calls on our Chicago SIP trunk"* and receive immediate, actionable root-cause diagnoses. - **Natural Language PBX Configuration**: Non-technical office managers can provision IVR greetings, adjust call forwarding, or schedule holiday hours simply by instructing the Copilot. - **NOC Incident Mitigation**: Network engineers querying Ring2All SBC can execute instant SIP trace ladders, unblock false-positive firewall IPs, or rebalance dispatchers via conversational commands. - **100% Multi-Tenant Isolation**: Tool execution is strictly bound to the active user's immutable numeric `tenant_id` and `domain_id`. The AI cannot cross organizational boundaries. --- ## 3. User Experience & Chat Interface The Copilot is accessible from anywhere in the application via the floating action button (bottom right) or top navigation bar. ### Key Features of the Chat Interface - **Live Streaming Responses**: Text streams word-by-word with zero perceived latency. - **Interactive Tool Execution Cards**: When the Copilot calls an MCP tool, a collapsible tool execution card indicates the active tool name, input parameters, and execution status (e.g. `Executing: get_extension_status(1001)... [Completed]`). - **Markdown & Code Highlighting**: Outputs formatted tables, bullet points, dialplan XML snippets, and clickable links. - **Copy to Clipboard & Regenerate**: Quickly export diagnostic summaries to support tickets. - **Chat History & Context Switch**: Automatically updates conversation context when switching active domains. --- ## 4. Master System Prompt & Personalization To ensure rigorous telecom precision, the Copilot incorporates a **Master System Prompt** hardcoded into the platform backend: - **Domain Identity**: Establishes telecom domain expertise, VoIP protocols (SIP, RTP, WebRTC), Telephony dialplan rules, and Kamailio routing. - **Strict Grounding**: Instructs the model never to invent extensions, IP addresses, or PIN numbers, requiring explicit tool execution before answering factual questions. - **Conciseness & Actionability**: Prioritizes concise bullet points and direct diagnostic steps over lengthy conversational filler. ### User Custom Complement Administrators can supplement the Master System Prompt with organization-specific policies under **Admin → AI → AI Profiles**: - Add company operating procedures (e.g. *"Our primary escalation trunk is Gateway 3"*). - Specify custom terminology or preferred greeting phrasing. --- ## 5. Model Context Protocol (MCP) Integration The platform implements the standard Model Context Protocol (MCP), exposing an extensive library of typed, self-documenting tools: ### Available Tool Categories | Category | Tools Included | Description | |----------|----------------|-------------| | **Extensions & Users** | `list_extensions`, `get_extension_details`, `update_extension_status`, `reset_extension_password`, `diagnose_extension` | View, provision, and troubleshoot SIP endpoints, voicemail, and credentials. | | **Call Inspection & CDR** | `query_cdrs`, `get_cdr_summary`, `get_cdr_details`, `get_active_calls`, `hangup_call`, `diagnose_call_failure` | Analyze real-time call traffic, durations, MOS quality, SIP hangup causes, and call logs. | | **Media, NAT & Codecs** | `diagnose_media_nat`, `get_active_calls`, `query_sip_endpoints` | Deep inspection of RTP audio packet flow, one-way audio, SDP RFC1918 leaks, and NAT traversal. | | **Routing & Inbound** | `list_inbound_routes`, `get_ivr_menus`, `update_time_condition`, `diagnose_inbound_route`, `diagnose_outbound_route`, `diagnose_time_condition`, `simulate_dialplan_route` | Inspect auto-attendants, queue schedules, trunk failovers, priority routing, and dry-run dialplan routing. | | **Trunks & Gateways** | `list_gateways`, `get_gateway_status`, `reload_gateway`, `diagnose_gateway` | SIP carrier trunks, DNS A/SRV resolution, OPTIONS ping latency, and registration forensics. | | **Queues & ACD** | `list_queues`, `get_queue_status`, `diagnose_queue` | Call center queue strategy, live agent tiers, MOH/welcome audio assets, and drop rates. | | **Call Groups & Voicemail** | `list_ring_groups`, `get_ring_group_status`, `diagnose_ring_group`, `diagnose_voicemail` | Ring group member readiness, timeout collisions, mailbox quotas, greeting assets, and MWI. | | **Policy & Permissions** | `list_class_of_services`, `diagnose_call_permission` | Class of Service (CoS), Dial Rule Restrictions, Toll Allow tokens, and Outbound Route matching. | | **Device Provisioning** | `list_provisioning_devices`, `get_provisioning_device_status`, `diagnose_provisioning` | Auto-provisioning MAC mappings, vendor/model templates, HTTP/HTTPS ports, and Fail2ban status. | | **System & Security** | `get_system_health`, `reload_telephony_xml`, `diagnose_ip_security`, `diagnose_webrtc_service`, `diagnose_system_issue` | Top-level PBX triage, storage/inodes, TLS certificates, firewall drops, and Fail2ban jails. | --- ### 5.1 The 17-Tool Intelligent Multi-Layer Diagnostic Suite (Triad Pattern) The Ring2All PBX MCP server incorporates a **Triad Diagnostic Architecture** that moves systematically through every physical and logical layer of the PBX to perform Root Cause Analysis (RCA): ``` ┌────────────────────────────────────────────────────────────────────────┐ │ TRIAD ROOT CAUSE ANALYSIS (RCA) PIPELINE │ ├────────────────────────────────────────────────────────────────────────┤ │ 1. Database Configuration Layer │ │ • Checks table flags, parent profiles (CoS), routes, and parameters│ │ │ │ 2. Operating System & Storage Layer │ │ • Validates directory existence, write permissions (chmod/chown), │ │ disk space usage, and inode quotas. │ │ │ │ 3. Real-Time Telephony Engine (ESL & Sofia) Layer │ │ • Inspects SIP registrations, active channels, media bugs, packet │ │ loss/MOS, and scans recent engine log traces. │ │ │ │ 4. Synthesized RCA Outcome & Actionable Remediation │ │ • Outputs visual status (🟢 HEALTHY, 🟡 WARNING, 🔴 CRITICAL) │ │ with exact, one-click or copy-paste remediation commands. │ └────────────────────────────────────────────────────────────────────────┘ ``` #### Diagnostic Tools Matrix | # | Tool Name | Target Subsystem | Diagnostic Scope & Checks | |---|:---|:---|:---| | 1 | `diagnose_extension` | Extensions & Recordings | Checks `record_calls` flags, physical recordings path (`/usr/share/freeswitch/recordings`), write permissions, Sofia registration state, active call recording bugs, and recent log traces. | | 2 | `diagnose_media_nat` | Media Flow & NAT | Detects one-way audio (0 packets sent/received), private RFC1918 IP leaks in SDP, `ext-rtp-ip`/`ext-sip-ip` configuration, UDP 16384-32768 port range, and ICE/STUN failures. | | 3 | `diagnose_gateway` | SIP Trunks & Gateways | Performs DNS A and SRV resolution for carrier proxy, measures live SIP OPTIONS ping latency, inspects Sofia registration (`REGED`/`FAIL_WAIT`), and checks for SIP 401/403/408/503 errors. | | 4 | `diagnose_call_failure` | CDR & Forensics | Correlates call UUID or dialed number with SIP hangup codes, detects 32-second NAT ACK drops, early media drops (zero billsec), and audio MOS packet loss. | | 5 | `diagnose_ring_group` | Call Distribution | Validates member extension readiness (DND, call forwards, offline status), detects extension voicemail timeout collisions, and verifies fallback route integrity. | | 6 | `diagnose_voicemail` | Voicemail Boxes | Inspects mailbox storage quotas, greeting audio existence, write permissions, MWI message counts, and local MTA/SMTP mail delivery for voicemail-to-email. | | 7 | `diagnose_call_permission` | Policy & Permissions | Evaluates assigned Class of Service (CoS), Dial Rule Restrictions (blacklisted prefixes, international, 900), Toll Allow tokens, PIN prompts, and Outbound Route matching. | | 8 | `diagnose_provisioning` | Auto-Provisioning | Validates MAC address mapping, vendor/model template syntax, HTTP/HTTPS port reachability, Basic Auth credentials, phone IP Fail2ban bans, and web access logs. | | 9 | `diagnose_queue` | ACD Call Center | Checks queue strategy, live agent availability via ESL, hold music/welcome prompt files on disk, abandoned call metrics, and average wait time. | | 10 | `diagnose_inbound_route` | Inbound DIDs | Evaluates DID regex patterns, validates target destination integrity (detects orphaned routes), failover destinations, and schedule time conditions. | | 11 | `diagnose_outbound_route` | Outbound Routing | Simulates dial patterns against dial strings, verifies gateway health and registration, validates caller ID rules, and checks failover order. | | 12 | `diagnose_ivr_menu` | Auto-Attendant IVR | Checks greeting audio files on disk, validates all DTMF key destination targets (0-9, *, #), and verifies timeout/invalid fallback routes. | | 13 | `diagnose_webrtc_service` | WebRTC & Audio | Verifies TLS certificate validity and expiration for WSS (port 7443), Sofia internal profile binding, and DTLS-SRTP/ICE configuration. | | 14 | `diagnose_ip_security` | Perimeter Defense | Inspects Fail2ban jails (`freeswitch-dos`, `kamailio-dos`), nftables blacklists, Telephony ACL deny nodes, and recent 401/flood attack logs. | | 15 | `diagnose_time_condition` | Schedule Routing | Evaluates server time and timezone against linked Time Groups, calculates real-time Match/Non-Match routing, and checks manual override state. | | 16 | `diagnose_system_issue` | High-Level Triage | Evaluates symptoms, inspects core engine uptime, disk space/inodes, database connection latency, and routes administrators to the appropriate diagnostic tool. | | 17 | `simulate_dialplan_route` | End-to-End Dialplan Simulation | Simulates call routing logic exactly matching FreeSWITCH Lua engine. Tests internal extensions, DND, call forwardings, Ring Groups, Queues, IVR, Voicemail, Blacklists, Class of Service restrictions, Outbound Route priority, digit transformations (strip/prepend), and gateway Sofia readiness. | --- ## 6. Tool Execution & Telephony Capabilities ### Example 1: Diagnosing Call Recording Failure (`diagnose_extension`) > **User:** *"Why isn't extension 2000 recording any of its calls?"* > **Copilot Action:** Executes `diagnose_extension({ extensionNumber: "2000", checkRecordings: true })`. > **Copilot Response:** > - 🔍 **Configuration:** `record_calls` is `true`, format is `wav`, direction is `all`. > - 💾 **Storage & Filesystem:** Storage directory `/usr/share/freeswitch/recordings/domain_1/archive/2000` exists, but is owned by `root:root` with permissions `0755`. Telephony process running as `freeswitch` was denied write access (`EACCES`). > - ⚡ **Telephony Engine:** Extension is registered (`ONLINE`). Active calls have not attached the `record_session` media bug due to filesystem permission error. > - 🔴 **Status:** CRITICAL — Write permission denied. > - 🎯 **Remediation:** Run `chown -R freeswitch:freeswitch /usr/share/freeswitch/recordings && chmod -R 775 /usr/share/freeswitch/recordings`. ### Example 2: One-Way Audio & NAT Traversal (`diagnose_media_nat`) > **User:** *"We can hear the client, but the client cannot hear us on external calls."* > **Copilot Action:** Executes `diagnose_media_nat({ extension: "1002" })`. > **Copilot Response:** > - 🔍 **Configuration:** Sofia External profile has `ext-rtp-ip` set to `192.168.1.100` (private RFC1918 IP) instead of the server public IP or `autonat:`. > - 💾 **Port Allocation:** RTP port range configured for UDP 16384-32768. > - ⚡ **Engine State:** SDP offer sent to carrier contains private IP in the connection data (`c=IN IP4 192.168.1.100`), causing the remote carrier to send audio to an unreachable address. > - 🔴 **Status:** CRITICAL — RFC1918 Private IP leaked in SDP. > - 🎯 **Remediation:** Navigate to **Settings → Technology → SIP Profiles → External** and update **Ext-RTP-IP** and **Ext-SIP-IP** to `autonat:` or the public WAN IP, then restart Sofia profile. ### Example 3: 32-Second Call Drops Forensics (`diagnose_call_failure`) > **User:** *"Calls drop automatically after roughly 30 seconds."* > **Copilot Action:** Executes `diagnose_call_failure({ limit: 5 })`. > **Copilot Response:** > - 🔍 **CDR Analysis:** Identified 4 recent calls with `billsec: 32` and `hangup_cause: RECOVERY_ON_TIMER_EXPIRE`. > - ⚡ **Forensic Finding:** The PBX answered the call and sent `SIP/2.0 200 OK`. The client's firewall dropped the returning `ACK` packet due to aggressive NAT UDP timeout or SIP ALG interference, triggering a standard RFC 3261 transaction timeout. > - 🟡 **Status:** WARNING — SIP ACK Transaction Timeout (NAT/Firewall). > - 🎯 **Remediation:** Disable SIP ALG on the remote router and verify UDP port 5060/5061 NAT keepalive interval is set to 25 seconds. --- ## 7. Security, RBAC & Multi-Tenant Isolation ### 1. Invariant Numeric ID Resolution The Copilot strictly queries the database using immutable numeric IDs (`tenant_id: number`, `domain_id: number`). Mutable strings or slugs are never accepted as authority tokens, eliminating cross-tenant privilege escalation. ### 2. MCP Tool Roles (Role-Based Access Control) Not all users should have equal tool permissions. Under **Admin → AI → Tool Profiles**, administrators configure granular MCP Tool Roles: - **Read-Only Auditor**: Allowed to call `query_cdr_records` and `get_system_health`; prohibited from calling `hangup_call` or `reload_freeswitch_xml`. - **PBX Administrator**: Allowed full extension and routing tools; prohibited from carrier gateway or Kamailio SBC perimeter commands. - **Superadmin**: Full access to all telephony and system tools. --- ## 8. CLI Copilot Assistant (`ring2all-copilot`) For terminal-based system administration, the platform bundles an interactive CLI tool installed in `/usr/local/bin`: ```bash # Launch interactive assistant ring2all-copilot # Run direct command with single-domain auto-detection ring2all-copilot "Show extensions that haven't registered in the last 7 days" ``` The CLI automatically reads local environment credentials, connects to the local PostgreSQL database and Telephony Server socket, and executes tools directly in the shell. --- ## 9. Troubleshooting & Verification ### Verify MCP Server Health ```bash # Check if API MCP endpoint is active curl -s http://127.0.0.1:3001/api/telephony/ai/health ``` ### Review Copilot Audit Logs Every tool executed by the Copilot is permanently logged with user ID, execution timestamp, arguments, and return status in `public.audit_logs`: ```sql SELECT created_at, user_id, action, resource_type, details FROM public.audit_logs WHERE action LIKE 'COPILOT_TOOL%' ORDER BY created_at DESC LIMIT 10; ``` --- *Documentation updated: September 2026*