MCP Tool Roles Module Documentation
Table of Contents
Section titled “Table of Contents”- Module Overview (Technical)
- Module Overview (Commercial & Business Value)
- 🎯 User Roles & Key Capabilities
- Visual Interface & Form Structure
- AI Governance & Model Context Protocol Execution Architecture
- Common Scenarios & Operational Playbooks
- Troubleshooting & Diagnostic Commands
- Model Context Protocol (MCP) AI Integration
- Glossary
1. Module Overview (Technical)
Section titled “1. Module Overview (Technical)”The MCP Tool Roles module (public.mcp_roles) implements enterprise AI governance, fine-grained access control (RBAC), and automated diagnostic safety boundaries for the entire Ring2All BSS subsystem. Powered by the open standard Model Context Protocol (MCP), AI Copilots and automated NOC diagnostic agents interact with carrier customer accounts, real-time OCS charging, rating decks, DID routing, firewall rules, and server hardware telemetry exclusively within the strict bounds defined by these profiles.
Data Model & System Linkage
Section titled “Data Model & System Linkage” ┌────────────────────────────────────────────────────────────────────────┐ │ MCP Role Entity (public.mcp_roles) │ │ • id: bigint (Canonical Invariant Numeric Primary Key) │ │ • uuid: uuid (Public API & SSO Identifier) │ │ • name: VARCHAR(100) (e.g. "Super Administrator", "Billing Operator")│ │ • description: TEXT (Tool Scope & Risk Classification Narrative) │ │ • tools: JSONB (Explicit Allowed Function Execution Array) │ │ • is_system: BOOLEAN (System Immutability Flag) │ │ • is_default: BOOLEAN (Auto-Assignment Flag for New AI Personas) │ │ • is_active: BOOLEAN (Operational State Flag) │ └───────────────────────────────────┬────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ Managed AI Model Context Protocol Tool Catalog │ │ │ │ [1. Customer Accounts & Wallets] │ │ • list_billing_customers • get_billing_customer │ │ • create_billing_customer • update_billing_customer │ │ • delete_billing_customer • adjust_customer_balance │ │ • update_customer_status • get_customer_wallet_ledger │ │ │ │ [2. Services, Plans & Rate Cards] │ │ • list_billing_plans • get_billing_plan │ │ • create_billing_plan • update_billing_plan │ │ • delete_billing_plan • list_active_subscriptions │ │ • create_customer_subscription • update_customer_subscription │ │ • cancel_customer_subscription • list_rate_cards │ │ • create_rate_card • update_rate_card │ │ • delete_rate_card • create_rate_card_destination │ │ • delete_rate_card_destination • lookup_rate_by_prefix │ │ • simulate_call_rating │ │ │ │ [3. Telecom Nodes & Carrier Providers] │ │ • list_telecom_nodes_status • sync_telecom_node │ │ • create_telecom_node • update_telecom_node │ │ • delete_telecom_node • list_carrier_providers │ │ • get_carrier_provider • create_carrier_provider │ │ • update_carrier_provider • delete_carrier_provider │ │ • list_did_inventory • create_did_number │ │ • update_did_routing • delete_did_number │ │ │ │ [4. Financial Reports & OCS Telephony] │ │ • list_invoices_summary • get_invoice_details │ │ • create_invoice • send_invoice_email │ │ • void_invoice • list_recent_transactions │ │ • get_financial_dashboard_kpis • query_rated_cdrs │ │ • query_rated_mdrs • get_accounting_journal_summary │ │ • get_live_calls_telemetry • disconnect_live_call_ocs │ │ │ │ [5. System Settings & Administration] │ │ • get_branding_settings • update_branding_settings │ │ • get_payment_gateways_status • update_payment_gateway_config │ │ • test_email_delivery • list_billing_users │ │ • create_billing_user • update_billing_user │ │ • delete_billing_user • get_user_audit_logs │ │ • list_role_profiles • create_role_profile │ │ • update_role_profile • delete_role_profile │ │ • list_mcp_tool_roles • create_mcp_tool_role │ │ • update_mcp_tool_role • delete_mcp_tool_role │ │ • list_api_keys • create_api_key │ │ • revoke_api_key │ │ │ │ [6. Firewall, Network & Security] │ │ • get_firewall_status • list_firewall_rules │ │ • create_firewall_rule • update_firewall_rule │ │ • delete_firewall_rule • block_ip_address │ │ • unblock_ip_address • get_ai_security_events │ │ • get_network_server_settings • list_certificates │ │ • list_fraud_alerts • resolve_fraud_alert │ │ │ │ [7. Maintenance & AI Integration] │ │ • get_system_maintenance_status • list_backup_history │ │ • create_system_backup • list_ai_providers │ │ • create_ai_provider • update_ai_provider │ │ • delete_ai_provider • list_ai_profiles │ │ • create_ai_profile • update_ai_profile │ │ • delete_ai_profile │ │ │ │ [8. Diagnostics & System Health] │ │ • analyze_server_health (CPU, RAM, Disks, OCS Telemetry, RCA) │ │ • diagnose_ocs_realtime_pipeline (Rating latency, node heartbeat, OCS)│ │ • diagnose_unrated_cdrs (Unbilled CDRs, zero-cost, revenue leaks) │ │ • diagnose_margin_leakage (Negative margins, carrier arbitrage) │ │ • diagnose_customer_billing_config (Balances, limits, rate cards) │ │ • diagnose_rate_card_coverage (Zero-rate audit, leakage detection) │ │ • diagnose_did_routing (PBX targets, SBC perimeter node sync) │ │ • diagnose_payment_gateways (Stripe API credentials, webhook secrets) │ │ • diagnose_telecom_node_sync (Voice node pings, connectivity checks) │ └────────────────────────────────────────────────────────────────────────┘PostgreSQL Schema Architecture (public.mcp_roles)
Section titled “PostgreSQL Schema Architecture (public.mcp_roles)”- Primary Key: Invariant numeric
idensures strict referential integrity withpublic.users.mcp_role_id. - Wildcard & Array Matching: The
toolscolumn stores a JSONB array of approved tool function names or the wildcard["*"]granting full system execution. - Risk Categorization: Tools are tagged with risk indicators:
LOW(read-only queries and diagnostic metrics),MEDIUM(configuration mutations), andHIGH(destructive drops, wallet deductions, IP blocks, and live call disconnects).
2. Module Overview (Commercial & Business Value)
Section titled “2. Module Overview (Commercial & Business Value)”- Elimination of Financial Hallucinations: Prevents Large Language Models from executing destructive financial adjustments or balance mutations without explicit human governance.
- Autonomous NOC Root Cause Analysis (RCA): The
analyze_server_healthtool synthesizes hardware metrics (CPU load, RAM pressure, disk partition utilization) with real-time OCS charging engine status to diagnose voice service degradations in seconds. - Proactive Toll Leakage Prevention: The
diagnose_rate_card_coveragetool inspects destination decks for missing international routes or dangerous $0.000000/min destinations before calls are dispatched. - Perimeter Synchronization Assurance: The
diagnose_did_routinganddiagnose_telecom_node_synctools ensure telephone numbers and customer SIP routing policies are perfectly mirrored between Ring2All BSS, Ring2All PBX, and Ring2All SBC.
3. 🎯 User Roles & Key Capabilities
Section titled “3. 🎯 User Roles & Key Capabilities”| User Role | Key Capabilities | Core Operational Workflows |
|---|---|---|
| Super Administrator | Full Unrestricted Access (*) |
Manages all MCP tool roles, authorizes high-risk financial and firewall operations, and reviews platform-wide AI audit logs. |
| Billing Operations & Accounts | Customer, Rating, Invoice, & Diagnostic Tools | Provisions customer subscriptions, executes wallet credit adjustments, simulates call rating, runs invoice billing cycles, and audits rate cards. |
| Telecom & Carrier Engineer (NOC) | Node, DID, OCS, Firewall, & Diagnostic Tools | Audits voice node synchronization, manages wholesale carrier DID routing, disconnects stuck calls in OCS, and executes server health diagnostics. |
| Read-Only Auditor & Compliance | Telemetry, Invoices, Logs, & Diagnostic Tools | Reviews financial KPIs, inspects immutable ledger entries, audits user activity logs, and performs read-only system health checks. |
4. Visual Interface & Form Structure
Section titled “4. Visual Interface & Form Structure”Level 1 — MCP Tool Roles List View
Section titled “Level 1 — MCP Tool Roles List View”Displays all registered MCP tool roles, indicating whether they possess wildcard (*) access or specific tool counts, assigned user counts, system protection badges, and creation timestamps.
Level 2 — MCP Tool Role Creation & Edit Form
Section titled “Level 2 — MCP Tool Role Creation & Edit Form”The form view combines role metadata with an interactive Authorized AI MCP Tools Matrix featuring one-click system presets, risk severity badges, category toggles, real-time tool search, and multi-language localized labels.
Interactive Form Controls Reference
Section titled “Interactive Form Controls Reference”- Role Name: Unique identifier for the MCP role (e.g.,
Telecom & Carrier Engineer (NOC)). - Description: Purpose and scope of the tools granted under this profile.
- Quick Presets: One-click assignment buttons:
Full Access (*): Grants execution rights for all tools across all categories.Billing Operator: Grants customer management, subscriptions, rating, invoices, and diagnostic tools.Telecom & NOC Engineer: Grants node synchronization, carrier providers, DIDs, OCS supervisor, firewall, and server health tools.Read-Only Auditor & Telemetry: Restricts tools strictly to read-only financial KPIs, logs, and diagnostic evaluations.
- Tool Matrix: Categorized accordion lists displaying tool name, localized description, risk level badge (
LOW,CONFIG,DESTRUCTIVE), and activation toggle.
5. AI Governance & Model Context Protocol Execution Architecture
Section titled “5. AI Governance & Model Context Protocol Execution Architecture” ┌────────────────────────────────┐ │ Administrative User / Copilot │ └───────────────┬────────────────┘ │ 1. Conversational Prompt: "Diagnose why customer ACC-1002 cannot place calls" ▼ ┌────────────────────────────────┐ │ AI Model (LLM Provider) │ └───────────────┬────────────────┘ │ 2. Propose Tool Call: diagnose_customer_billing_config({ customerId: "1002" }) ▼ ┌────────────────────────────────────────────────────────┐ │ MCP Tool Role Authorization Guard │ │ • Verify Fastify JWT & user session │ │ • Check public.users.mcp_role_id │ │ • Query public.mcp_roles.tools │ └───────────────┬────────────────────────────────────────┘ │ ┌──────────┴──────────┐ │ Authorized? │ ▼ ▼ ┌───────────────┐ ┌─────────────────────────────────────────────────┐ │ YES │ │ NO │ ├───────────────┤ ├─────────────────────────────────────────────────┤ │ Execute Tool │ │ Intercept & Reject: HTTP 403 Forbidden │ │ via Fastify │ │ "Access Denied: Your MCP Tool Role does not │ │ Service Layer │ │ authorize execution of tool '...'." │ └───────────────┘ └─────────────────────────────────────────────────┘6. Common Scenarios & Operational Playbooks
Section titled “6. Common Scenarios & Operational Playbooks”Playbook 1: Diagnosing Customer Call Failures with AI
Section titled “Playbook 1: Diagnosing Customer Call Failures with AI”- The billing operator asks the Copilot: “Customer GlobalTech reports their outbound calls are dropping. Check their billing status.”
- The AI model invokes
diagnose_customer_billing_config:{ "customerId": "c7a8b9c0-1234-5678-90ab-cdef12345678" } - The tool audits the wallet balance, credit limit, assigned rate card, and DID routing, identifying a zero balance on a prepaid account.
- The Copilot outputs actionable guidance: “Customer balance is $0.00. Advise customer to top up their wallet or apply a authorized credit adjustment.”
Playbook 2: Periodic Rate Card Toll Leakage Audit
Section titled “Playbook 2: Periodic Rate Card Toll Leakage Audit”- The telecom administrator invokes
diagnose_rate_card_coverageagainst the wholesale termination deck. - The tool flags 3 destination prefixes with rate
$0.000000/minand detects missing international prefix definitions. - The administrator uses
create_rate_card_destinationvia the Copilot to correct the rates immediately.
7. Troubleshooting & Diagnostic Commands
Section titled “7. Troubleshooting & Diagnostic Commands”Verifying MCP Roles in Database
Section titled “Verifying MCP Roles in Database”# Query registered MCP tool roles and active statussu - postgres -c "psql -d ss_billing -c 'SELECT id, name, is_system, is_default, jsonb_array_length(tools) AS tool_count, is_activeFROM public.mcp_rolesORDER BY id ASC;'"Inspecting Specific Allowed Tools for a User
Section titled “Inspecting Specific Allowed Tools for a User”# Check assigned MCP tool permissions for user ID 1su - postgres -c "psql -d ss_billing -c 'SELECT u.username, m.name AS mcp_role, m.toolsFROM public.users uJOIN public.mcp_roles m ON m.id = u.mcp_role_idWHERE u.id = 1;'"8. Model Context Protocol (MCP) AI Integration
Section titled “8. Model Context Protocol (MCP) AI Integration”The Ring2All BSS MCP Server (ring2all-bss) exposes over 50 tools across 8 operational categories for AI integration.
Core Diagnostic Tools Reference
Section titled “Core Diagnostic Tools Reference”| Tool Name | Risk Tier | Primary Function |
|---|---|---|
analyze_server_health |
LOW |
Returns complete hardware CPU/RAM/Swap, filesystem storage, OS release, Node.js/V8, PostgreSQL latency, and OCS engine metrics. |
diagnose_customer_billing_config |
LOW |
Audits customer prepaid/postpaid rules, wallet credit limits, assigned retail rate cards, and DID routing targets. |
diagnose_rate_card_coverage |
LOW |
Audits destination prefix coverage, detects $0.00 zero-rates (toll leakage risk), and flags anomalous high rates. |
diagnose_did_routing |
LOW |
Validates DID customer association, route target (extension vs SIP URI), SBC perimeter synchronization, and E911 compliance. |
diagnose_payment_gateways |
LOW |
Audits Stripe API credentials and webhook signing secret configuration in the environment. |
diagnose_telecom_node_sync |
LOW |
Pings all registered FreeSWITCH PBX and Kamailio SBC nodes, reports latency, and verifies cluster connectivity. |
Sample MCP Tool Execution: analyze_server_health
Section titled “Sample MCP Tool Execution: analyze_server_health”Request Payload
Section titled “Request Payload”{ "name": "analyze_server_health", "arguments": {}}Response Payload
Section titled “Response Payload”{ "system": { "hostname": "billing-prod-01", "platform": "linux", "distribution": "Debian GNU/Linux 13 (trixie)", "architecture": "x64", "uptime": "14 days, 6 hours, 22 minutes", "loadAverage": [0.42, 0.38, 0.35], "cpuCount": 8, "cpuModel": "AMD EPYC 7763 64-Core Processor", "memory": { "total": "32.00 GB", "free": "18.45 GB", "used": "13.55 GB", "usagePercent": "42.3%" }, "storage": [ { "filesystem": "/dev/sda1", "mountPoint": "/", "total": "245.8G", "used": "68.2G", "available": "165.1G", "usagePercent": "29%" } ] }, "runtime": { "nodeVersion": "v22.14.0", "v8Version": "12.4.254.21-node.21", "processUptime": "4 days, 12 hours", "processMemory": { "rss": "184.25 MB", "heapTotal": "112.50 MB", "heapUsed": "88.10 MB" } }, "database": { "status": "ONLINE", "pingLatencyMs": 1.45, "size": "4.82 GB", "activeConnections": 18 }, "telephony": { "subsystem": "Ring2All BSS Convergent Rating & OCS Engine", "activeSupervisedCalls": 24, "ocsEngineStatus": "ONLINE", "totalNodesRegistered": 3, "connectedNodes": 3, "lastPingLatencyMs": 2.1 }, "overallHealth": "HEALTHY", "issues": [], "recommendations": [ "System hardware, database latency, and real-time charging engines are operating within nominal thresholds." ]}Sample MCP Tool Execution: diagnose_customer_billing_config
Section titled “Sample MCP Tool Execution: diagnose_customer_billing_config”Request Payload
Section titled “Request Payload”{ "name": "diagnose_customer_billing_config", "arguments": { "customerId": "c7a8b9c0-1234-5678-90ab-cdef12345678" }}Response Payload
Section titled “Response Payload”{ "status": "WARNING", "customerId": "c7a8b9c0-1234-5678-90ab-cdef12345678", "customerName": "Nexus Communications LLC", "accountStatus": "active", "billingType": "prepaid", "wallet": { "balance": "$4.50", "creditLimit": "$0.00", "currency": "USD" }, "assignedRateCard": "Retail Standard Deck 2026", "activeSubscriptionsCount": 2, "assignedDidsCount": 3, "issues": [ "Low prepaid balance alert: $4.50 remaining.", "DID +13055550199 is not synchronized to the Ring2All SBC perimeter engine." ], "recommendations": [ "Notify customer to recharge before services get suspended.", "Trigger node synchronization for DID +13055550199." ]}Conversational AI Prompts for Copilot
Section titled “Conversational AI Prompts for Copilot”English Prompts
Section titled “English Prompts”- “Analyze the server health and tell me if memory or disk partitions are near capacity.”
- “Diagnose the billing configuration for customer Acme Corp and verify if they have a rate card assigned.”
- “Run a toll leakage audit on rate card ‘Wholesale Deck A’ to check for zero-rate destinations.”
- “Check if all telephone numbers for customer 104 are properly synced with the Ring2All SBC.”
- “Verify the connectivity and ping latency to all registered Ring2All voice nodes.”
Spanish Prompts (Español)
Section titled “Spanish Prompts (Español)”- “Analiza la salud del servidor y dime si la memoria o el disco están cerca del límite.”
- “Diagnostica la configuración de facturación del cliente Acme Corp y verifica si tiene tarifario asignado.”
- “Ejecuta una auditoría de fugas de ingresos en el tarifario ‘Wholesale Deck A’ para buscar tarifas en cero.”
- “Verifica si todos los números telefónicos del cliente 104 están sincronizados con Ring2All SBC.”
- “Comprueba la conectividad y latencia de ping de todos los nodos de voz Ring2All registrados.”
9. Glossary
Section titled “9. Glossary”- Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and enterprise telecommunications systems.
- Online Charging System (OCS): Real-time rating and credit control engine that supervises live telephony sessions, enforcing prepaid balance limits and instantaneous call termination.
- Rate Card Deck: Collection of destination prefix matching rules and per-minute tariffs used to rate outbound voice calls and SMS messages.
- Toll Leakage: Financial loss incurred when telecommunications traffic is terminated through wholesale carriers without corresponding retail billing charges (often caused by $0.00 destination rates).
- DID (Direct Inward Dialing): Public telephone number mapped to an inbound routing target (PBX extension, IVR, Ring Group, or external SIP URI).