---
title: "MCP Role Profiles (AI Tool Governance)"
description: "Documentation for MCP Role Profiles"
---

## Table of Contents
1. [Overview & AI Governance Architecture](#1-overview--ai-governance-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Tool Assignment Parameters](#5-field-reference--tool-assignment-parameters)
6. [SBC MCP Tool Catalog & Action Capabilities](#6-sbc-mcp-tool-catalog--action-capabilities)
7. [The Official System MCP Role Profiles](#7-the-official-system-mcp-role-profiles)
8. [Runtime Execution & Security Guard Mechanics](#8-runtime-execution--security-guard-mechanics)
9. [Troubleshooting & Verification](#9-troubleshooting--verification)
10. [Model Context Protocol (MCP) AI Integration](#10-model-context-protocol-mcp-ai-integration)
11. [Glossary](#11-glossary)

---

## 1. Overview & AI Governance Architecture

In **Ring2All SBC**, the **MCP Role Profiles** module provides strict, zero-trust security governance over the artificial intelligence tools exposed by the **Model Context Protocol (MCP)** server. The platform's integrated AI assistant (**NOC Copilot**) interacts directly with running SIP Engine daemons, Media Relay proxies, and live routing tables to diagnose network faults, explain SIP ladder traces, provision carrier gateways, and adjust perimeter firewall states.

```
                    ┌─────────────────────────────────────────────────┐
                    │               User Session Context              │
                    │         (user_id, assigned mcp_role_id)         │
                    └────────────────────────┬────────────────────────┘
                                             │
                                  Prompt: "Unban IP 192.168.1.50"
                                             │
                                             ▼
                    ┌─────────────────────────────────────────────────┐
                    │            Ring2All SBC NOC Copilot             │
                    │               (LLM Engine / Claude)             │
                    └────────────────────────┬────────────────────────┘
                                             │
                                Formulates Tool Call Request:
                           {"tool": "unban_ip_address", "ip": "..."}
                                             │
                                             ▼
                    ┌─────────────────────────────────────────────────┐
                    │          MCP Security Enforcement Guard         │
                    │         (assertUserCanExecuteTool Check)        │
                    └────────────────────────┬────────────────────────┘
                                             │
                     ┌───────────────────────┴───────────────────────┐
                     │                                               │
                     ▼                                               ▼
         [Tool in allowed_tools]                       [Tool NOT in allowed_tools]
          Invoke Engine JSON-RPC                        Reject Call Immediately
          htable.delete ipban ...                       403 Forbidden: Unauthorized
```

To eliminate the risk of prompt injection, unauthorized carrier tampering, or unintended dialplan reloading, every AI tool invocation (`tools/call`) is cryptographically and logically validated against the user's assigned MCP Role Profile before executing.

---

## 2. Business & Operational Significance

* **Prompt Injection & Hallucination Containment**: Guarantees that even if an external caller or malicious SIP header attempts prompt injection against the AI Copilot, the model cannot execute tools outside the user's permitted profile.
* **Controlled AI Autonomy in Mission-Critical Telecom**: Allows Tier-1 technicians to use AI for diagnostic querying (e.g., inspecting SIP ladders and QoS metrics) while strictly withholding permission to alter carrier weights, provision wholesale trunks, or execute shell commands.
* **Granular Segregation Between Diagnostics and Configuration**: Separates read-only analytical tools (`get_sip_traces`, `get_traffic_analytics`) from state-modifying actions (`reload_dispatchers`, `create_carrier`, `unban_ip_address`).
* **Compliance & AI Governance Auditing**: Maintains an immutable evidentiary trail of all AI tool executions, recording the human operator on whose behalf the AI tool was called.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **AI Systems Architect** | Copilot Governance Policy | Define MCP tool profiles, structure tool catalogs, and enforce organizational AI boundaries. |
| **NOC Director** | Safe Operational Acceleration | Empower support engineers with AI-assisted diagnostics while ensuring operational stability. |
| **Security Operations Analyst** | AI Threat & Action Auditing | Review AI tool call logs, investigate blocked execution attempts, and audit unban actions. |
| **SBC Telecom Engineer** | Conversational Telemetry Inspection | Utilize authorized tools to query real-time dispatcher health, analyze MOS scores, and isolate trunk faults. |
| **AI Platform Copilot / Administration Agent** | Self-Introspection & AI Tool Boundary Verification | Inspect assigned tool permissions, verify AI role scopes, and ensure compliant execution within authorized telephony boundaries. |

---

## 4. Visual Interface & Layout

The MCP Role Profiles interface displays all registered AI tool profiles, their allowed tool counts, active statuses, and an interactive tool selection modal for role provisioning.

### 4.1 MCP Role Profiles List View
Displays existing AI tool profiles, assigned tools, default indicators, and management action buttons.

![MCP Role Profiles List View](/screenshots/sbc/admin/mcp-roles/mcp-roles-list.png)

### 4.2 MCP Role Configuration Form
Modal editor providing tool group selectors, individual tool checkboxes, name, description, and status toggles.

![MCP Role Configuration Form](/screenshots/sbc/admin/mcp-roles/mcp-role-form.png)

---

## 5. Field Reference & Tool Assignment Parameters

| Parameter Name | Data Type | Options / Format | Description |
| :--- | :--- | :--- | :--- |
| **Role Name** | String | Alphanumeric (e.g., `NOC Network Engineer`) | Descriptive identifier indicating organizational AI responsibility. |
| **Description** | Text | Text string | Operational purpose and scope of tool clearance. |
| **Quick Presets** | Selector | `Super Admin`, `NOC Engineer`, `Carrier Mgr`, `Security Auditor`, `Monitor` | Prepopulated tool bundles for rapid provisioning without individual checkbox selection. |
| **Allowed Tools** | Array / Set | Tool names or `*` wildcard | Exhaustive array of permitted MCP tools for this profile. |
| **Default Profile** | Switch | Boolean (`true` / `false`) | Automatically assigned to newly onboarded users if not explicitly specified. |
| **Active Status** | Switch | Boolean (`true` / `false`) | Toggle to immediately suspend AI access for all accounts bound to this role profile. |

---

## 6. SBC MCP Tool Catalog & Action Capabilities

Ring2All SBC provides a comprehensive suite of enterprise-grade MCP tools organized into functional subsystems, enabling autonomous diagnostics, full lifecycle CRUD configuration, and automated remediation:

### 6.1 SIP Tracing & Diagnostics
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `get_sip_traces` | Read-Only | Queries live SIP transaction traces and extracts packet headers for a specified Call-ID. |
| `explain_sip_call` | Read-Only | Synthesizes SIP trace ladders into human-readable fault explanations and identifies root cause error codes. |
| `capture_and_analyze_sip_trace` | Diagnostic | Captures signaling packets for an active call and provides comprehensive timeline analysis. |
| `diagnose_sip_error_spikes` | Diagnostic | Scans live SIP traces in real time for surges of 4xx/5xx/6xx error responses, calculates error rates per carrier and caller, and automates triage for common signaling failures. |
| `get_sip_trace_capture_status` | Read-Only | Checks whether global SIP packet capture and tracing is currently active in the SIP Engine. |
| `set_sip_trace_capture_status` | State-Modifying | Enables or disables real-time SIP signaling capture in the tracing subsystem. |

### 6.2 Dispatchers & Load Balancing
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `get_dispatcher_status` | Read-Only | Checks the availability, latency, and status (Active/Probing/Inactive) of carrier trunks. |
| `diagnose_dispatcher` | Diagnostic | Evaluates round-robin health, latency statistics, and socket states for a dispatcher node. |
| `create_dispatcher` | State-Modifying | Adds a new SIP destination node to an existing dispatcher load-balancing set. |
| `update_dispatcher` | State-Modifying | Modifies destination URI, capacity weight, flags, or priority for a dispatcher node. |
| `delete_dispatcher` | State-Modifying | Removes a gateway node from a dispatcher group. |
| `set_dispatcher_state` | State-Modifying | Manually enables, disables, or places a carrier gateway into probing mode. |
| `reload_dispatchers` | State-Modifying | Executes live reload of carrier gateways from PostgreSQL into SIP Engine memory without dropping calls. |

### 6.3 Carriers & Gateway Pools
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_carriers` | Read-Only | Dumps carrier routing groups, assigned gateways, and cost tiers. |
| `get_carrier_status` | Read-Only | Inspects live connection state, active channels, and health status for a specific carrier. |
| `diagnose_carrier` | Diagnostic | Evaluates carrier availability, recent failure rates, response times, and LCR participation. |
| `create_carrier` | State-Modifying | Provisions a new upstream wholesale carrier gateway pool with routing parameters. |
| `update_carrier` | State-Modifying | Updates carrier IP, port, protocol, concurrency limits, or operational state. |
| `delete_carrier` | State-Modifying | Deletes a carrier trunk from the SBC routing system. |
| `get_carrier_quality_metrics` | Read-Only | Compiles ASR, ACD, and PDD performance metrics for a specific carrier trunk. |

### 6.4 LCR & Dynamic Routing
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_lcr_routes` | Read-Only | Evaluates prefix trees to explain which carrier trunk will be chosen for a given dialed number. |
| `get_lcr_route_status` | Read-Only | Inspects active route status, priority sequence, and gateway lists for an LCR rule. |
| `diagnose_lcr_route` | Diagnostic | Simulates digit normalization, prefix matching, and gateway failover sequences for a dial pattern. |
| `create_lcr_route` | State-Modifying | Defines a new dynamic routing rule with prefix patterns and ordered carrier gateways. |
| `update_lcr_route` | State-Modifying | Modifies route priority, destination prefix, or assigned carrier gateway groups. |
| `delete_lcr_route` | State-Modifying | Removes an LCR route rule from the dynamic routing matrix. |
| `reload_drouting_rules` | State-Modifying | Reloads dynamic routing rules and LCR prefix trees in shared memory without service interruption. |

### 6.5 DID Numbers & Inbound Mapping
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_dids` | Read-Only | Lists inbound Direct Inward Dialing (DID) numbers, routing destinations, and tenant mappings. |
| `get_did_status` | Read-Only | Inspects configuration and routing status for a specific DID number. |
| `diagnose_did` | Diagnostic | Simulates inbound translation, header manipulation, and endpoint matching for an incoming DID. |
| `create_did` | State-Modifying | Adds a new inbound DID number with destination translation rules. |
| `update_did` | State-Modifying | Updates routing destination, tenant assignment, or fallback handling for a DID. |
| `delete_did` | State-Modifying | Removes a DID translation record from the SBC database. |

### 6.6 PBX Endpoints & Core Clusters
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_sbc_endpoints` | Read-Only | Lists internal PBX core nodes and cluster dispatch destinations. |
| `create_sbc_endpoint` | State-Modifying | Registers a new PBX core cluster node in the SBC routing table. |
| `update_sbc_endpoint` | State-Modifying | Modifies host IP, port, weight, or active status for a PBX endpoint. |
| `delete_sbc_endpoint` | State-Modifying | Removes a PBX core node from the SBC ingress pool. |

### 6.7 SIP Domains & Multi-Tenancy
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_sip_domains` | Read-Only | Lists all multi-tenant SIP domains managed by the SBC perimeter. |
| `get_sip_domain_status` | Read-Only | Inspects domain routing group and active registration status. |
| `diagnose_sip_domain` | Diagnostic | Validates DNS SRV resolution, TLS certificate matching, and dispatcher mapping for a domain. |
| `create_sip_domain` | State-Modifying | Provisions a new multi-tenant SIP domain on the SBC. |
| `update_sip_domain` | State-Modifying | Modifies domain parameters, default routing set, or security policy. |
| `delete_sip_domain` | State-Modifying | Removes a SIP domain from the active perimeter database. |
| `reload_sip_domains` | State-Modifying | Triggers instant in-memory reload of domain routing tables in the SIP Engine. |

### 6.8 SIP Message Rules (SMR)
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_smr_rules` | Read-Only | Lists header transformation and packet manipulation rules. |
| `get_smr_rule_status` | Read-Only | Inspects matching criteria and transformation actions of an SMR rule. |
| `diagnose_smr_rule` | Diagnostic | Tests header regex substitutions, URI rewriting, and condition evaluations on sample SIP messages. |
| `create_smr_rule` | State-Modifying | Creates a new SIP message manipulation rule (e.g., stripping privacy headers, rewriting From URI). |
| `update_smr_rule` | State-Modifying | Updates match conditions, regex expressions, or replacement actions for an SMR rule. |
| `delete_smr_rule` | State-Modifying | Removes a message manipulation rule from the processing pipeline. |

### 6.9 Trusted IPs & ACL Permissions
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_trusted_ips` | Read-Only | Lists trusted IP addresses and CIDR subnets exempt from Digest authentication. |
| `diagnose_acl_permission` | Diagnostic | Verifies IP authorization, subnet matching, and permission group membership for a remote host. |
| `add_trusted_ip` | State-Modifying | Authorizes a new trusted IP address or CIDR range in the perimeter access control table. |
| `remove_trusted_ip` | State-Modifying | Revokes trusted status from an IP address or subnet. |
| `reload_acl_permissions` | State-Modifying | Executes instant reload of permissions tables in the SIP Engine. |

### 6.10 SIP Accounts & Wholesale Trunks
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_sip_accounts` | Read-Only | Lists subscriber SIP accounts, authentication methods, and capacity limits. |
| `get_sip_account_status` | Read-Only | Inspects registration state, contact bindings, and concurrency counters for an account. |
| `diagnose_sip_account` | Diagnostic | Verifies Digest credentials, HA1 hash integrity, registration timers, and ACL matching. |
| `create_sip_account` | State-Modifying | Creates a new subscriber account with Digest credentials and channel limits. |
| `update_sip_account` | State-Modifying | Modifies SIP credentials, authentication realm, or channel caps. |
| `delete_sip_account` | State-Modifying | Removes a subscriber SIP account from the SBC. |

### 6.11 Microsoft Teams Direct Routing
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `list_msteams_tenants` | Read-Only | Lists configured Microsoft Teams customer tenants and SIP trunks. |
| `get_msteams_status` | Read-Only | Inspects TLS handshake state and OPTIONS keepalive telemetry with Microsoft PSTN gateways. |
| `diagnose_msteams` | Diagnostic | Diagnoses mutual TLS authentication, domain verification, and Microsoft OPTIONS responses. |
| `create_msteams_tenant` | State-Modifying | Provisions a new Microsoft Teams customer tenant with Direct Routing parameters. |
| `update_msteams_tenant` | State-Modifying | Modifies tenant FQDN, TLS profile, or domain routing parameters. |
| `delete_msteams_tenant` | State-Modifying | Removes a Microsoft Teams tenant configuration. |

### 6.12 WebRTC Gateway
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `diagnose_webrtc` | Diagnostic | Verifies Secure WebSocket (WSS) listeners, DTLS-SRTP certificates, and ICE/STUN/TURN relay readiness. |

### 6.13 Media Relay & Voice QoS
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `get_rtpengine_status` | Read-Only | Retrieves Media Relay daemon health, active media sessions, and port pool utilization. |
| `diagnose_media_relay` | Diagnostic | Checks control socket responsiveness, active audio streams, and kernel-space relay telemetry. |
| `get_voice_qos_telemetry` | Read-Only | Extracts real-time jitter, packet loss percentage, round-trip delay, and MOS score across active streams. |
| `analyze_call_qos_stream` | Diagnostic | Performs forensic quality analysis on an active or finished call, isolating latency spikes and jitter bursts. |
| `diagnose_one_way_audio` | Diagnostic | Analyzes call CDRs and SIP trace SDP offer/answer messages to detect one-way audio streams, asymmetric packet loss, extreme jitter, and NAT IP mismatches. |
| `get_qos_alert_policy` | Read-Only | Queries active voice quality alarm thresholds and automated notification rules. |
| `update_qos_alert_policy` | State-Modifying | Configures MOS drop thresholds, packet loss trigger levels, and alert recipient lists. |

### 6.14 Perimeter Security & Anti-Flood
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `get_banned_ips` | Read-Only | Queries the perimeter memory hash table to list all IP addresses currently blocked by Pike anti-flood. |
| `ban_ip_address` | State-Modifying | Immediately blocks a hostile IP address in the perimeter firewall and memory tables. |
| `unban_ip_address` | State-Modifying | Purges an IP address from memory hash tables and unblocks it in the firewall to restore service. |
| `diagnose_perimeter_security` | Diagnostic | Analyzes packet drop rates, Pike offenders, active kernel bans, and geo-firewall hit rates. |

### 6.15 AI Perimeter Guard & Threat Forensics
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `sbc_get_threat_intelligence_summary` | Read-Only | Retrieves real-time security posture, total banned hosts, active threats, and attack distribution. |
| `sbc_analyze_ip_security` | Diagnostic | Computes threat risk scores, behavioral anomalies, and IRSF patterns for a target IP address. |
| `sbc_list_security_incidents` | Read-Only | Lists recent security events, brute-force attempts, header anomalies, and automated mitigations. |
| `sbc_mitigate_threat_ip` | State-Modifying | Executes autonomous threat containment and applies immediate kernel ban rules against malicious hosts. |

### 6.16 STIR/SHAKEN Caller Identity
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `get_stirshaken_config` | Read-Only | Inspects STIR/SHAKEN signing and verification configuration, certificate paths, and attestation defaults. |
| `update_stirshaken_config` | State-Modifying | Updates attestation levels (A, B, C), certificate store paths, or verification policy. |
| `verify_caller_identity` | Diagnostic | Simulates PASSporT token validation and cryptographic verification for a specified caller number. |

### 6.17 System Core, Maintenance & Governance
| Tool Identifier | Access Level | Description & Operational Impact |
| :--- | :--- | :--- |
| `analyze_server_health` | Read-Only | Deep server hardware, OS distribution, CPU/RAM/Swap load, storage partition capacity, database latency, and system engine telemetry. |
| `get_sbc_health` | Read-Only | Retrieves CPU load, memory utilization, process health, and database connection pools. |
| `get_sbc_audit_logs` | Read-Only | Inspects administrative audit trails, user actions, and system mutation records. |
| `log_sbc_audit_event` | State-Modifying | Records an administrative or autonomous compliance event in the audit trail. |
| `get_engine_settings` | Read-Only | Inspects low-level SIP Engine parameters, memory allocations, and network socket bindings. |
| `update_engine_settings` | State-Modifying | Updates operational parameters in the core SIP Engine configuration. |
| `get_billing_settings` | Read-Only | Queries real-time CDR rating and billing engine integration configurations. |
| `list_tls_profiles` | Read-Only | Lists configured TLS encryption profiles, cipher suites, and verification modes. |
| `get_tls_profile_status` | Read-Only | Inspects validity, cipher settings, and handshake statistics for a TLS profile. |
| `reload_tls_profiles` | State-Modifying | Reloads TLS certificates and cryptographic contexts in the SIP Engine without dropping connections. |
| `list_mtrees` | Read-Only | Lists memory trees (mtrees) used for high-speed prefix matching and LCR. |
| `reload_mtrees` | State-Modifying | Reloads memory tree prefix structures in shared memory. |
| `list_htables` | Read-Only | Inspects in-memory hash tables used for caching, rate limiting, and ban tracking. |
| `get_htable_entries` | Read-Only | Dumps entries from a specific in-memory hash table. |
| `reload_htables` | State-Modifying | Reloads hash table configurations from the database. |
| `execute_rpc_command` | Restricted | Executes a sanitized management RPC command on the SIP Engine with strict parameter validation. |
| `get_rpc_suggestions` | Read-Only | Provides syntax suggestions and parameter descriptions for management RPC commands. |
| `list_sbc_users` | Read-Only | Lists administrative user accounts and assigned permission roles. |
| `get_sbc_user` | Read-Only | Retrieves detailed profile and clearance information for an administrative user. |
| `list_sbc_role_profiles` | Read-Only | Lists RBAC role profiles defined on the SBC with assigned user counts. |
| `get_sbc_role_profile` | Read-Only | Retrieves detailed module permissions for an RBAC role profile. |
| `list_sbc_mcp_roles` | Read-Only | Lists all AI Copilot MCP tool roles with total allowed tool counts and assigned operators. |
| `get_sbc_mcp_role` | Read-Only | Retrieves detailed tool whitelist and category clearance for a specific MCP role. |

---

## 7. The Official System MCP Role Profiles

Ring2All SBC provides five official pre-configured AI governance profiles:

### 7.1 Super Administrator
* **Scope**: Wildcard (`["*"]`)
* **Purpose**: Full autonomous access to all diagnostic, analytical, CRUD provisioning, and state-modifying tools. Reserved exclusively for senior infrastructure engineers and platform administrators.

### 7.2 NOC Network Engineer
* **Scope**: Advanced Diagnostics + Active Remediation + State Modification
* **Capabilities**: Comprehensive SIP tracing, packet ladder forensics, dispatcher failover, carrier health diagnosis, Media Relay inspection, voice QoS analysis, and perimeter IP unbanning.
* **Key Tools**: `get_sip_traces`, `explain_sip_call`, `capture_and_analyze_sip_trace`, `get_dispatcher_status`, `diagnose_dispatcher`, `set_dispatcher_state`, `reload_dispatchers`, `list_carriers`, `get_carrier_status`, `diagnose_carrier`, `list_lcr_routes`, `get_lcr_route_status`, `diagnose_lcr_route`, `reload_drouting_rules`, `get_rtpengine_status`, `diagnose_media_relay`, `get_voice_qos_telemetry`, `analyze_call_qos_stream`, `get_banned_ips`, `unban_ip_address`, `ban_ip_address`, `diagnose_perimeter_security`, `get_sbc_health`, `analyze_server_health`.

### 7.3 LCR & Carrier Routing Manager
* **Scope**: Carrier Lifecycle, Routing Matrices, Prefix Trees & Inbound DIDs
* **Capabilities**: Full CRUD provisioning of wholesale carriers, dynamic LCR routes, prefix tables, inbound DIDs, PBX endpoints, and traffic analytics inspection.
* **Key Tools**: `list_carriers`, `get_carrier_status`, `diagnose_carrier`, `create_carrier`, `update_carrier`, `delete_carrier`, `list_lcr_routes`, `get_lcr_route_status`, `diagnose_lcr_route`, `create_lcr_route`, `update_lcr_route`, `delete_lcr_route`, `reload_drouting_rules`, `list_dids`, `get_did_status`, `diagnose_did`, `create_did`, `update_did`, `delete_did`, `list_sbc_endpoints`, `create_sbc_endpoint`, `update_sbc_endpoint`, `delete_sbc_endpoint`, `get_carrier_quality_metrics`, `get_traffic_analytics`, `get_top_destinations`, `get_sbc_cdrs`.

### 7.4 Perimeter Security & Compliance Auditor
* **Scope**: Host Defense, Anti-Flood, ACL Lists, STIR/SHAKEN & Forensic Logs
* **Capabilities**: Management of Pike anti-flood hash tables, trusted IP access lists, threat intelligence scoring, STIR/SHAKEN identity verification, and administrative audit inspection.
* **Key Tools**: `get_banned_ips`, `ban_ip_address`, `unban_ip_address`, `diagnose_perimeter_security`, `list_trusted_ips`, `add_trusted_ip`, `remove_trusted_ip`, `diagnose_acl_permission`, `reload_acl_permissions`, `sbc_get_threat_intelligence_summary`, `sbc_analyze_ip_security`, `sbc_list_security_incidents`, `sbc_mitigate_threat_ip`, `get_stirshaken_config`, `update_stirshaken_config`, `verify_caller_identity`, `get_sbc_audit_logs`, `log_sbc_audit_event`, `get_sbc_health`, `analyze_server_health`.

### 7.5 Read-Only SBC Monitor
* **Scope**: Strictly View-Only Telemetry
* **Capabilities**: Real-time observability across active calls, SIP traces, voice QoS metrics, carrier availability, and cluster health without permission to alter running daemons or database records.
* **Key Tools**: `explain_sip_call`, `get_sip_traces`, `get_sip_trace_capture_status`, `get_dispatcher_status`, `diagnose_dispatcher`, `list_carriers`, `get_carrier_status`, `diagnose_carrier`, `list_lcr_routes`, `get_lcr_route_status`, `diagnose_lcr_route`, `list_dids`, `get_did_status`, `diagnose_did`, `list_sbc_endpoints`, `list_sip_domains`, `get_sip_domain_status`, `diagnose_sip_domain`, `get_rtpengine_status`, `diagnose_media_relay`, `get_voice_qos_telemetry`, `analyze_call_qos_stream`, `get_banned_ips`, `diagnose_perimeter_security`, `diagnose_webrtc`, `sbc_get_threat_intelligence_summary`, `get_sbc_health`, `analyze_server_health`, `get_traffic_analytics`, `get_top_destinations`.

---

## 8. Runtime Execution & Security Guard Mechanics

When the AI model determines that a tool should be executed, the request passes through the **MCP Tool Authorization Guard**:

```typescript
export async function assertUserCanExecuteTool(
  userId: number,
  toolName: string,
  db: KyselyDatabase
): Promise<void> {
  const user = await db
    .selectFrom('users as u')
    .leftJoin('mcp_roles as r', 'r.id', 'u.mcp_role_id')
    .select(['r.allowed_tools as allowedTools', 'r.is_active as isActive'])
    .where('u.id', '=', userId)
    .executeTakeFirst();

  if (!user || !user.isActive) {
    throw new ForbiddenError('User has no active MCP Tool Role assigned');
  }

  const tools: string[] = typeof user.allowedTools === 'string'
    ? JSON.parse(user.allowedTools)
    : (user.allowedTools || []);

  // Super Admin wildcard or explicit tool match
  if (tools.includes('*') || tools.includes(toolName)) {
    return; // Authorized to execute
  }

  throw new ForbiddenError(`MCP tool '${toolName}' is not permitted for the user's role`);
}
```

---

## 9. Troubleshooting & Verification

### Inspecting Active MCP Roles in Database
Verify configured AI tool permissions directly on the SBC:
```bash
sudo -u postgres psql -d sbc_admin -c "
SELECT id, name, is_system, allowed_tools 
FROM mcp_roles 
ORDER BY id;
"
```

### Auditing Blocked Tool Invocations
Inspect security audit logs for unauthorized AI tool attempts:
```bash
sudo -u postgres psql -d sbc_admin -c "
SELECT created_at, user_id, action, details 
FROM audit_log 
WHERE action LIKE '%mcp_tool_denied%' 
ORDER BY created_at DESC 
LIMIT 10;
"
```

---

## 10. Model Context Protocol (MCP) AI Integration

Ring2All SBC exposes dedicated Model Context Protocol (MCP) governance tools enabling AI agents to inspect MCP role configurations, verify tool whitelists, and perform self-introspection on permitted boundaries.

### Available MCP Tools

| Tool Name | Operation | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_sbc_mcp_roles` | Read | Low (`read`) | List all AI Copilot MCP tool roles with total allowed tool counts, default flags, and assigned operator counts. |
| `get_sbc_mcp_role` | Read | Low (`read`) | Retrieve the detailed tool whitelist and category clearance for a specific MCP role by UUID, slug, or ID. |

### Tool Schemas & Parameter Definitions

#### `list_sbc_mcp_roles`
```json
{
  "name": "list_sbc_mcp_roles",
  "description": "List Model Context Protocol (MCP) AI Tool RBAC roles in Ring2All SBC with permitted tool counts and assigned users.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}
```

#### `get_sbc_mcp_role`
```json
{
  "name": "get_sbc_mcp_role",
  "description": "Get detailed MCP tool whitelist and permissions for a specific MCP role by UUID, slug, or ID.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "MCP role UUID, slug, or numeric ID"
      }
    },
    "required": ["identifier"]
  }
}
```

### Realistic Payload Examples

#### Query Request (`get_sbc_mcp_role`)
```json
{
  "identifier": "noc_network_engineer"
}
```

#### Successful Response (`get_sbc_mcp_role`)
```json
{
  "success": true,
  "data": {
    "mcpRole": {
      "id": 2,
      "uuid": "8e14f092-23c1-4ba2-b5e0-47120aef8912",
      "name": "NOC Network Engineer",
      "slug": "noc_network_engineer",
      "description": "Perimeter network diagnostics, SIP traces ladder inspection, Media Relay QoS telemetry, dispatcher state management, and real-time firewall mitigation.",
      "is_default": false,
      "is_active": true,
      "users_count": 6,
      "tools": [
        "get_sip_traces",
        "explain_sip_call",
        "capture_and_analyze_sip_trace",
        "get_dispatcher_status",
        "diagnose_dispatcher",
        "reload_dispatchers",
        "list_carriers",
        "get_carrier_status",
        "diagnose_carrier",
        "get_rtpengine_status",
        "diagnose_media_relay",
        "get_voice_qos_telemetry",
        "analyze_call_qos_stream",
        "get_banned_ips",
        "unban_ip_address",
        "ban_ip_address",
        "diagnose_perimeter_security",
        "get_sbc_health",
        "list_sbc_users",
        "get_sbc_user",
        "get_sbc_email_alarm_settings"
      ],
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-09-08T11:00:00Z"
    }
  }
}
```

### Natural Language Prompt Scenarios

#### English (AI Copilot Self-Verification)
> *"Check which MCP tools are allowed for my active role profile and confirm if I have permission to unban an IP address or reload SIP Engine dispatchers."*

#### Spanish (Auditoría de Roles de IA)
> *"Lista todos los perfiles de herramientas MCP disponibles en el SBC y muestra cuántos operadores tienen asignado el perfil con acceso completo ('super_admin')."*

### Enterprise AI Safety Guardrails
* **Self-Contained Role Introspection**: AI models can query their assigned tool whitelist to gracefully explain permission boundaries to human operators without triggering runtime 403 errors.
* **Wildcard Execution Containment**: The `super_admin` wildcard (`*`) is restricted strictly to accounts verified with root administrative credentials.

---

## 11. Glossary

* **MCP (Model Context Protocol)**: An open standard created by Anthropic that enables AI assistants to securely discover and invoke tools, data sources, and APIs.
* **NOC Copilot**: Ring2All SBC's specialized conversational AI assistant fine-tuned for telecom troubleshooting and SIP diagnostics.
* **Tool Call**: A structured JSON object generated by an LLM requesting the host application to run a specific function with provided arguments.
* **Prompt Injection**: A cybersecurity vulnerability where an attacker manipulates an AI model's instructions through crafted text inputs.