---
title: "MCP Tool Roles Module Documentation"
description: "Documentation for MCP Tool Roles"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Module Overview (Technical)](#1-module-overview-technical)
5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
7. [The 5 Official System MCP Tool Roles](#4-the-5-official-system-mcp-tool-roles)
8. [Configuration Sections](#5-configuration-sections)
9. [Settings Reference](#6-settings-reference)
10. [Common Scenarios & Examples](#7-common-scenarios--examples)
11. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
12. [Limitations & Important Notes](#8-limitations--important-notes)
13. [Troubleshooting Tips](#9-troubleshooting-tips)
14. [Glossary](#10-glossary)

---

## Navigation & Access

To access the MCP Tool Roles governance module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Admin**.
3. Under **Administration**, click **MCP Tool Roles** (`/mcp-roles`).
4. To create a new MCP tool role profile, click the **+ Add MCP Role** button (`/mcp-roles/new`).
5. To view, edit, or duplicate an existing MCP tool role profile, click on the profile row or the action controls (`/mcp-roles/:id`).

---

## Screenshots & Visual Interface

### MCP Tool Roles List View
The MCP Tool Roles list view displays all configured AI governance profiles (PBX Super Administrator, Call Center Supervisor, VoIP Technician, Standard Extension User, Security & PBX Auditor), listing authorized tool counts, default profile designations, active statuses, and administrative actions.
![MCP Tool Roles List](/screenshots/admin/admin/mcp-roles-list.png)

### MCP Tool Role Configuration Form & Tool Catalog
The MCP tool role configuration editor allows system administrators to assign granular execution rights over specific telephony tools (Telephony Event Socket (ESL) commands, CDR querying, eavesdropping, queue management) with bulk category selection, search filtering, and active status toggles.
![MCP Tool Role Configuration Form](/screenshots/admin/admin/mcp-roles-form.png)

---

## 🎯 User Roles & Key Capabilities

MCP Tool Roles establish zero-trust boundaries over autonomous AI capabilities across organizational tiers:

| Role | Key Capabilities & Operational Scope |
|------|--------------------------------------|
| **PBX Super Administrator** | Unrestricted access (`*`) to all Telephony Server telephony commands, Kamailio binrpc APIs, CDR metrics, queue controls, and user administration via AI Copilot. |
| **Call Center Supervisor** | Authorized to interact with ACD queue tools, agent state toggles, live active call eavesdropping, barge-in commands, and queue callback metrics. |
| **VoIP / PBX Technician** | Authorized to inspect SIP gateways, register extensions, modify outbound/inbound routes, adjust time groups, and reboot SIP endpoints via provisioning tools. |
| **Standard Extension User** | Self-service capabilities limited strictly to personal extension status, DND toggling, personal forwarding, personal voicemail, and phonebook lookups. |
| **Security & Telephony Auditor** | Strictly read-only tool capabilities: queries CDR records, audits log profile activity, reviews firewall status, and analyzes system health without execution or modification powers. |

---

## 1. Module Overview (Technical)

### What Are MCP Tool Roles?

**MCP Tool Roles** provides the **AI Governance & Authorization Layer** for the Model Context Protocol (MCP) server integrated into the Ring2All PBX platform. 

While **Role Profiles** govern what a human user can see and click in the web frontend, and **Log Profiles** control what actions get audited, **MCP Tool Roles** strictly govern **what programmatic telephony commands an AI Agent, Assistant, or Copilot can execute** when acting on behalf of an authenticated user.

### The Four Pillars of Access Control

```
                  ┌─────────────────────────────────────────────────┐
                  │                 USER ACCOUNT                    │
                  │   (Auth: Argon2id, JWT, MFA, Multi-Tenant)      │
                  └────────┬────────────────┬────────────────┬──────┘
                           │                │                │
          ┌────────────────▼───┐  ┌─────────▼──────────┐  ┌──▼────────────────┐
          │    ROLE PROFILE    │  │    LOG PROFILE     │  │   MCP TOOL ROLE   │
          │   (RBAC Modules)   │  │ (Audit & Notif.)   │  │ (AI Tools RBAC)   │
          ├────────────────────┤  ├────────────────────┤  ├───────────────────┤
          │ • Read / List      │  │ • Log Create       │  │ • Telephony Event Socket (ESL)  │
          │ • Create / Insert  │  │ • Log Edit         │  │ • Kamailio binrpc │
          │ • Edit / Update    │  │ • Log Delete       │  │ • RTPEngine QoS   │
          │ • Delete / Destroy │  │ • Push / Email Not.│  │ • CDRs & Telephony│
          └────────────────────┘  └────────────────────┘  └───────────────────┘
```

### Authorization Architecture & Runtime Validation

Whenever an AI Assistant (e.g. Platform Copilot, Voice Agent, or Extensions Chatbot) requests a tool call via the Model Context Protocol (`tools/call`), the backend server intercepts the request and verifies the caller's assigned MCP Tool Role:

```typescript
export async function assertUserCanExecuteTool(
  userId: number | string,
  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.status as status'])
    .where('u.id', '=', userId)
    .executeTakeFirst();

  if (!user || user.status !== 'active') {
    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 Administrator wildcard (*) or explicit tool permission
  if (tools.includes('*') || tools.includes(toolName)) {
    return; // Authorized
  }

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

### Database Storage

- **Table**: `ss_admin.mcp_roles`
- **Key Columns**:
  - `id`: Auto-incrementing primary integer identifier.
  - `uuid`: Universally unique identifier.
  - `tenant_id`: Multi-tenant ownership (NULL for global system profiles).
  - `name`: Display name of the MCP role profile.
  - `description`: Detailed description of the profile's operational scope.
  - `allowed_tools`: JSONB array of permitted tool slugs (or `["*"]`).
  - `is_default`: Boolean indicating the default profile for newly provisioned users.
  - `status`: Lifecycle state (`active` / `inactive`).

---

## 2. Module Overview (Commercial/Business)

### Why AI Tool Governance Matters

Deploying generative AI into a mission-critical telecommunications softswitch introduces serious risks if tools lack granular authorization:
- **Preventing Unauthorized Eavesdropping**: Supervisors should be able to whisper or listen into calls, but standard extension users must never be allowed to bridge into third-party calls.
- **Preventing Accidental Outages**: Network technicians can restart Sofia SIP profiles or reload gateways, but sales representatives using an AI assistant should only be able to place outbound calls and query their voicemail.
- **Compliance & Privacy (GDPR / HIPAA / PCI-DSS)**: Financial and healthcare environments require proof that AI chatbots cannot query call recordings or CDR metadata without audited authorization.

MCP Tool Roles ensure enterprise telephony operators can deliver powerful AI assistants with zero fear of privilege escalation.

---

## 3. Module Overview (End User/Administrator)

### Who Configures MCP Tool Roles?

- **SuperAdmin**: Can create, clone, edit, and assign MCP tool roles across all domains and tenants.
- **Tenant Administrator**: Can view and select allowed tool profiles for tenant users based on platform provisioning.

### User Account Binding

Every user in the PBX can be assigned a specific MCP Tool Role from the **Users** module (`/users/:id` ➔ **Security & Access**). If no role is selected, the platform automatically applies the role designated with `is_default = true`.

---

## 4. The 5 Official System MCP Tool Roles

The platform includes five pre-configured system roles out of the box:

| Role Name | Scope of Allowed Tools | Description |
|:---|:---|:---|
| **PBX Super Administrator (Full Access)** | `["*"]` | Unrestricted access to execute all telephony commands, Telephony Server CLI commands, security threat diagnostics, and call modifications. |
| **Call Center Supervisor** | 15 Tools | Queue monitoring, live call barge-in, eavesdropping, whisper coaching, agent status toggles, recording playback, and CDR stats. |
| **VoIP Technician** | 14 Tools | Sofia SIP profile inspection/rescanning, gateway diagnostics, SIP registrations, channel variable inspection, MOS quality metrics, and PBX CLI execution. |
| **Standard Extension User** | 8 Tools | Self-service capabilities: originate calls, transfer active calls, hangup calls, presence status, personal voicemail playback, and company phonebook search. |
| **Security & PBX Auditor** | 12 Tools | CDR investigation, security events review, blocked IP listing, call quality MOS inspection, system health, and quarantining compromised extensions. |

---

## 5. Configuration Sections

### General Information Box
- **Profile Name**: Descriptive label identifying the profile's tier and audience.
- **Description**: Purpose statement summarizing the operational permissions granted.
- **Default Profile**: Checkbox to designate this profile as the automatic fallback for new user accounts.
- **Status**: Toggle between `Active` and `Inactive`.

### Allowed Tools Catalog Box
Organized into categorized tool groups with individual toggles and group select-all switches:
1. **Call Management & Dialplan Routing**: `originate_call`, `transfer_call`, `hangup_call`, `get_active_calls`, `simulate_dialplan_route`.
2. **Supervision & Coaching**: `eavesdrop_call`, `whisper_call`, `barge_call`.
3. **Queue & Agent Operations**: `list_queues`, `get_queue_status`, `list_queue_agents`, `set_agent_status`.
4. **SIP & Infrastructure Diagnostics**: `get_sofia_status`, `get_sip_profile_status`, `rescan_sip_profile`, `list_registrations`, `list_gateways`, `get_gateway_status`, `execute_fs_cli`.
5. **Quality & Performance**: `inspect_call_quality_mos`, `get_fs_uptime`, `get_system_memory`, `get_system_status`, `analyze_server_health`.
6. **Security & Auditing**: `diagnose_pbx_security_threats`, `list_audit_logs`, `list_security_events`, `list_blocked_ips`, `quarantine_compromised_extension`.
7. **Personal & Voicemail**: `get_my_presence`, `get_my_extension_status`, `get_my_voicemails`, `list_recordings`, `play_recording`, `search_phonebook`.

---

## 6. Settings Reference

| Field | Type | Default | Required | Description |
|:---|:---|:---|:---|:---|
| **Name** | Text | `""` | Yes | Unique name for the MCP Tool Role profile. |
| **Description** | Text | `""` | No | Operational description explaining the profile's permissions. |
| **Is Default** | Boolean | `false` | No | If true, automatically assigned to new users without an explicit role. |
| **Status** | Select | `active` | Yes | Lifecycle status (`active` or `inactive`). |
| **Allowed Tools** | Array (JSONB) | `[]` | Yes | List of tool names or `["*"]` for complete system access. |

---

## 7. Common Scenarios & Examples

### Scenario 1: Creating a "Tier 1 Helpdesk" MCP Role
A support technician needs to check if an extension is registered and view active calls, but must never run raw CLI commands or eavesdrop on private calls:
1. Navigate to **Admin ➔ Administration ➔ MCP Tool Roles**.
2. Click **+ Add MCP Role**.
3. Name: `Tier 1 Helpdesk Support`.
4. Check the following tools:
   - `get_active_calls`
   - `list_registrations`
   - `get_registration_details`
   - `get_my_extension_status`
   - `inspect_call_quality_mos`
5. Leave `execute_fs_cli`, `eavesdrop_call`, and `barge_call` unchecked.
6. Click **Save Changes**.

### Scenario 2: Assigning the Role to a User
1. Navigate to **Admin ➔ Administration ➔ Users**.
2. Edit user `sarah.connor` (`/users/2`).
3. In the **Security & Access** section, locate the **MCP Tool Role** dropdown.
4. Select `Tier 1 Helpdesk Support`.
5. Click **Save Changes**. All AI Assistant interactions by Sarah will now be restricted to those 5 tools.

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform provides self-governing MCP tools that allow administrators and automated scripts to audit and inspect MCP Tool Roles.

### MCP Tools Reference

| Tool Name | Operation | Description | Risk Level |
|-----------|-----------|-------------|------------|
| `list_mcp_roles` | Read | Lists all MCP Tool Roles governing AI Copilot access, allowed tools counts, and assigned users. | Low |
| `get_mcp_role_status` | Read | Retrieves the exact tool whitelist, categories, and assigned user accounts for a specific MCP role. | Low |

### JSON Schema Definitions

#### `list_mcp_roles`
```json
{
  "name": "list_mcp_roles",
  "description": "Lists all MCP Tool Roles governing AI Copilot access and allowed telephony tools.",
  "parameters": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by MCP role name or tool category"
      }
    }
  }
}
```

#### `get_mcp_role_status`
```json
{
  "name": "get_mcp_role_status",
  "description": "Retrieves detailed allowed tool whitelists and assigned users for an MCP Tool Role.",
  "parameters": {
    "type": "object",
    "properties": {
      "role_id": {
        "type": "number",
        "description": "Internal numeric MCP Tool Role identifier"
      },
      "name": {
        "type": "string",
        "description": "MCP Tool Role name (e.g. 'Call Center Supervisor', 'VoIP Technician')"
      }
    }
  }
}
```

### Natural Language Prompt Examples

#### English
- *"List all configured MCP Tool Roles and their active statuses."*
- *"Show the exact list of allowed tools for the 'VoIP / PBX Technician' MCP role."*
- *"Check which users are assigned to the 'Super Administrator' AI governance role."*

#### Spanish
- *"Muestra todos los roles de herramientas MCP y cuántas herramientas tienen permitidas."*
- *"Consulta la lista de herramientas habilitadas para el rol MCP 'Call Center Supervisor'."*
- *"¿Qué usuarios tienen asignado el rol de IA 'Auditor de Seguridad'?"*

### Enterprise Safeguards & Guardrails
1. **Real-Time Revocation**: Any modification to an MCP Tool Role takes effect immediately on the very next tool call made by any connected AI session.
2. **Fail-Safe Deny**: If a user account lacks an active MCP role, the backend automatically denies 100% of tool execution attempts.
3. **Protected Presets**: Predefined system MCP presets cannot be deleted or renamed.

---

## 8. Limitations & Important Notes

- **Real-Time Revocation**: Modifying an MCP Tool Role takes effect immediately on the very next tool call made by any connected AI session.
- **Protected Roles**: Default system profiles cannot be deleted. Administrators can clone them to create customized variations.
- **Fail-Safe Deny**: If a user account has no MCP role or an inactive role assigned, the MCP server automatically denies 100% of tool execution attempts.

---

## 9. Troubleshooting Tips

### Tool Call Fails with "ForbiddenError"
- Check the user's assigned role in `/users/:id`.
- Ensure the specific tool requested is included in `allowed_tools`.
- Verify the MCP role's status is set to `active`.

### AI Assistant Reports Command Unavailable
- If the AI says "I do not have permission to inspect SIP profiles," verify whether `get_sip_profile_status` is enabled for the user's role.

---

## 10. Glossary

| Term | Definition |
|:---|:---|
| **MCP (Model Context Protocol)** | Open protocol developed by Anthropic allowing AI models to securely connect to external tools and data sources. |
| **Platform Copilot** | Ring2All's integrated AI assistant providing natural language diagnostics and PBX management. |
| **ESL (Event Socket Layer)** | Telephony Server TCP socket interface used to monitor events and execute telephony commands. |
| **Barge-in** | Telephony feature allowing a supervisor to join a live two-party call as a three-way conference. |
| **Whisper** | Telephony coaching feature allowing a supervisor to speak to an internal agent without the external caller hearing. |

---

*Documentation last updated: September 2026*