Overview of Allegro MCP
Access Methods
You can access Allegro MCP in three ways.
Embedded Chat Widget (Billie)
Billie is the default AI assistant inside the Allegro UI. End users such as customer service representatives (CSRs) and billing analysts ask questions in plain English. Responses stream in real time as the agent reasons, calls tools, and produces answers. No setup is required—open the Allegro UI and start typing.
MCP Protocol
Allegro MCP speaks the standard Model Context Protocol over Streamable HTTP transport. Any MCP-compatible client—Claude Desktop, Claude Code, custom AI agents, or partner middleware—connects to the following endpoint with a Bearer token:
https://mcp.<environment>.ariasystems.net/allegro/mcp
Authenticated partners see only the tools their tool profile permits, and all data access is automatically scoped to their tenant. This is the recommended path for new AI-driven partner integrations.
REST Tool API
For systems that require direct programmatic access without an AI client, use the REST Tool API endpoints described in the following table.
| Endpoint | Purpose |
|---|---|
POST /api/tool |
Invoke a single tool with a JSON payload. |
GET /api/tools |
Discover available tools and their input schemas. |
The Allegro MCP admin console (allegro-mcp-ui) uses this transport, as do scripting, ETL, automation, and integration testing workflows.
Tool Domains
Allegro MCP exposes approximately 198 tools organized across nine domain hubs. The following table summarizes what each hub covers.
| Hub | What you can do |
|---|---|
| Customer | Account search and detail, subscriptions, billing profiles, balances, contacts, addresses. |
| Pricing & Monetization | Price offers, discount offers, bundles, rate schedules, pricing matrices, surcharges. Full price-offer lifecycle (create, configure, activate). |
| Billing | Transaction units, transaction aggregations, and balance units on the Allegro side. Accounts receivable items such as invoices, payments, credit and debit memos, statements, and write-offs are managed in Core Aria. |
| Mediation | Call Detail Record (CDR) file processing, raw usage records, mediation rules, usage errors, router configuration, and file reprocessing. |
| Configuration | Accumulators, currencies, allowances, rate units, time units, zone units, service types, account types, billing groups, taxation, dunning, payment methods, and invoice templates. |
| Usage Processing | Submit usage, monitor batch status, and search submissions. |
| Operations | Jobs, schedules, run history, and activity log. |
| Common | System properties, virtual time, health, currencies, locales, notifications, and event types. |
| Composite Skills |
Ten higher-level operations that wrap multi-step billing flows |
Trust and Safety
The following table summarizes the safety controls available for each category of concern.
| Concern | Control |
|---|---|
| Unauthorized actions | Approval workflows on configurable mutation tools. |
| Mistakes | Preview-then-commit pattern—you see what will happen before it happens, and you can discard. |
| Reversibility | Rollback assessment per executed action: what is reversible, how, and within what window. |
| Auditability | Every agent-driven action is recorded with actor, tool, input, before and after state, result, and timestamp. |
| Tenant isolation | The Bearer token's tenant claim binds every request to the partner's tenant—your customers cannot read each other's data. |
| Partner tool access | Each partner's tool profile restricts which tools they see and can invoke. |
| Cost runaway | Three-layer guardrails: per-conversation ceilings, per-tenant daily quotas, and runaway-loop detection. |
Configurable Limits and Policies
Every limit, threshold, and policy is operator-tunable via hot-reloadable configuration. Defaults are suitable for production but can be adjusted per environment or per tenant.
Cost Guardrails
| Setting | Default | Tunable per tenant? |
|---|---|---|
| Per-conversation input tokens | 100,000 | No (global) |
| Per-conversation output tokens | 50,000 | No (global) |
| Per-conversation total tokens | 150,000 | No (global) |
| Per-tenant daily quota | 5,000,000 tokens | Yes—per-tenant overrides supported |
| Quota warn threshold | 80 percent | No (global) |
| Runaway-loop detection threshold | 3 same-tool repeats with errors | No (global) |
| Runaway detection window | Last 8 tool calls | No (global) |
Mutation Policies
The default policy for any mutation is PREVIEW—you must commit after seeing what will change. The table below describes the three available policies.
| Policy | Behavior | Default scope |
|---|---|---|
DIRECT |
Executes immediately with no preview. | System operations: set_system_property, set_virtual_time, reload_cache, run_job_now, reprocess_cdr_file. |
PREVIEW |
Returns a preview first; you commit explicitly. | All create_*, update_*, and modify_* mutations. |
APPROVAL |
Requires preview plus external admin approval before commit. | High-risk mutations: change_account_status, cancel_subscription. |
Preview tickets expire after 300 seconds (5 minutes) by default if not committed. Mutations recorded in the audit trail are rollback-assessable for 30 minutes after execution by default.
Rate Limiting
The MCP HTTP transport applies per-profile rate limits using a token-bucket algorithm.
| Profile | Sustained rate | Burst |
|---|---|---|
FULL_ACCESS (internal or admin) |
600 per minute | 100 |
BILLING_READ_ONLY |
300 per minute | 50 |
PRICING_ADMIN |
300 per minute | 50 |
USAGE_PARTNER |
200 per minute | 30 |
MEDIATION_PARTNER |
200 per minute | 30 |
CONFIG_READ_ONLY |
300 per minute | 50 |
| Unauthenticated or unknown profile | 120 per minute | 20 |
Tool Access Profiles
Partner tokens carry a tool_profile claim that maps to a curated subset of tools. The out-of-the-box profiles are listed below.
FULL_ACCESS—all tools (internal use only).BILLING_READ_ONLY—30 read tools across Customer and Billing hubs.PRICING_ADMIN—billing read plus full Pricing and Monetization management.USAGE_PARTNER—usage submission plus read-only billing.MEDIATION_PARTNER—mediation operations (CDR, errors, rules).CONFIG_READ_ONLY—read-only access to all configuration.
You can define additional profiles by editing the tool-profile configuration and assigning the matching tool_profile claim in Keycloak.
Observability
Operations teams have visibility into the following areas.
- Per-tool latency—P50/P99 histograms per tool name, per tenant.
- Per-tenant token spend—input and output tokens by tenant and model for cost attribution.
- Conversation traces—distributed traces covering the full request lifecycle from MCP entry through tool dispatch, GraphQL call, and response.
- Cost guardrail events—termination counts by kind (ceiling, quota, or runaway) and quota-utilization percentage per tenant.
All metrics emit via OpenTelemetry (OTLP), so they ingest into the observability platform of your choice—Prometheus, Grafana Tempo, Datadog, and similar—without code changes.
Security
- All API communication uses HTTPS.
- Authentication uses OAuth 2.0 via Keycloak. Tokens refresh automatically with no re-entry windows.
- Partner tokens carry server-injected claims that determine tool visibility and tenant scope. The client cannot control either claim.
- Only the modern Streamable HTTP transport is exposed externally. The legacy MCP+SSE transport has been retired.
- Token claims, request bodies, and audit log entries are sanitized before logging—no sensitive personally identifiable information (PII) appears in logs.