AI Platform Copilot & Model Context Protocol (MCP)

Overview & Architecture
Commercial & Operational Value
User Experience & Chat Interface
Master System Prompt & Personalization
Model Context Protocol (MCP) Integration
Tool Execution & Telephony Capabilities
Security, RBAC & Multi-Tenant Isolation
CLI Copilot Assistant (ring2all-copilot)
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:

# 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

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

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