---
title: "MCP Tool Roles Module Documentation"
description: "Documentation for MCP Tool Roles, AI Governance, Advanced Diagnostics, and Server Health Telemetry in Ring2All BSS"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [AI Governance & Model Context Protocol Execution Architecture](#5-ai-governance--model-context-protocol-execution-architecture)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-glossary)

---

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

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                      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`)
* **Primary Key:** Invariant numeric `id` ensures strict referential integrity with `public.users.mcp_role_id`.
* **Wildcard & Array Matching:** The `tools` column 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), and `HIGH` (destructive drops, wallet deductions, IP blocks, and live call disconnects).

---

## 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_health` tool 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_coverage` tool inspects destination decks for missing international routes or dangerous $0.000000/min destinations before calls are dispatched.
* **Perimeter Synchronization Assurance:** The `diagnose_did_routing` and `diagnose_telecom_node_sync` tools ensure telephone numbers and customer SIP routing policies are perfectly mirrored between Ring2All BSS, Ring2All PBX, and Ring2All SBC.

---

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

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

![MCP Tool Roles List View](/screenshots/billing/admin/administration/mcp-roles/mcp-roles-list.png)

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

![MCP Tool Role Form View](/screenshots/billing/admin/administration/mcp-roles/mcp-roles-form.png)

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

```
 ┌────────────────────────────────┐
 │ 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

### Playbook 1: Diagnosing Customer Call Failures with AI
1. The billing operator asks the Copilot: *"Customer GlobalTech reports their outbound calls are dropping. Check their billing status."*
2. The AI model invokes `diagnose_customer_billing_config`:
   ```json
   { "customerId": "c7a8b9c0-1234-5678-90ab-cdef12345678" }
   ```
3. The tool audits the wallet balance, credit limit, assigned rate card, and DID routing, identifying a zero balance on a prepaid account.
4. 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
1. The telecom administrator invokes `diagnose_rate_card_coverage` against the wholesale termination deck.
2. The tool flags 3 destination prefixes with rate `$0.000000/min` and detects missing international prefix definitions.
3. The administrator uses `create_rate_card_destination` via the Copilot to correct the rates immediately.

---

## 7. Troubleshooting & Diagnostic Commands

### Verifying MCP Roles in Database
```bash
# Query registered MCP tool roles and active status
su - postgres -c "psql -d ss_billing -c '
SELECT id, name, is_system, is_default, jsonb_array_length(tools) AS tool_count, is_active
FROM public.mcp_roles
ORDER BY id ASC;'"
```

### Inspecting Specific Allowed Tools for a User
```bash
# Check assigned MCP tool permissions for user ID 1
su - postgres -c "psql -d ss_billing -c '
SELECT u.username, m.name AS mcp_role, m.tools
FROM public.users u
JOIN public.mcp_roles m ON m.id = u.mcp_role_id
WHERE u.id = 1;'"
```

---

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

| 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`

#### Request Payload
```json
{
  "name": "analyze_server_health",
  "arguments": {}
}
```

#### Response Payload
```json
{
  "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`

#### Request Payload
```json
{
  "name": "diagnose_customer_billing_config",
  "arguments": {
    "customerId": "c7a8b9c0-1234-5678-90ab-cdef12345678"
  }
}
```

#### Response Payload
```json
{
  "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

#### 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)
* *"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

* **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).