Working with the platform via an AI agent (MCP)
Purpose
AI agents (Claude Code, Cursor, VS Code, and other MCP clients) connect to the platform MCP server and help setup and support engineers: analyze routing and calls, check registrations and domain state, find model data and statistics, and answer from the reference.
The agent works read-only: objects cannot be created or changed via the MCP server. A human makes changes in the administrator or via the REST API — the agent will suggest what to fix and where.
Preparation
-
Create a user for the agent with a narrow set of roles: the agent sees the same as this user (preset roles). Do not use the domain administrator account unless the agent needs to see everything.
-
Create an integration channel of type
mcpand specify this user (opts.userid). The opts.allow_modify option remains disabled. -
Save the channel token (
token_local): it is shown in clear text once — on creation and reissue. -
If necessary, restrict the addresses from which the token is accepted (
remoteipmask) and the channel lifetime.
The mcp channel token is accepted only by the MCP server: direct requests with it to the REST API and /api are rejected.
Connecting the agent
Server address: https://<server>/mcp/v1. Use https: the token is passed in every request.
Claude Code:
claude mcp add --transport http era https://<server>/mcp/v1 --header "Authorization: Bearer <token>"
Cursor (~/.cursor/mcp.json or the project .cursor/mcp.json):
{"mcpServers": {"era": {"url": "https://<server>/mcp/v1", "headers": {"Authorization": "Bearer <token>"}}}}
VS Code (.vscode/mcp.json):
{"servers": {"era": {"type": "http", "url": "https://<server>/mcp/v1", "headers": {"Authorization": "Bearer <token>"}}}}
Any MCP client with Streamable HTTP transport that allows setting the Authorization header will work.
Clients requiring OAuth authorization (claude.ai connectors, Claude Desktop) are not yet supported.
Do not store the token file in a shared repository.
What to ask the agent
The agent selects tools by the question. Examples:
| Question | What the agent does |
|---|---|
A subscriber cannot reach 84951234567, figure out why and what to fix |
Routing test without a call, analysis of rules and providers |
Were there calls in the last 20 minutes? For the latest one show the signaling flow and how it ended |
Call list, SIP diagram by Call-ID |
Which accounts are not registered, were there registration errors? |
Registrations and registration errors |
Domain summary: license, active calls, scripts, conferences |
Domain state |
What call center call data is stored? Count requests by services for a week |
Data model, server-side aggregation |
What queue statistics indicators exist and what are their current values? |
Indicator dictionary, current values and archives |
How to configure busy forwarding? |
Search and read the reference, page links |
What is happening with the system and what to do? (master domain channel; in Claude Code — |
System state report, warning analysis, node state, actions |
The full tool list and limitations — MCP server (/mcp/v1).
Data and security
-
The agent acts on behalf of the channel user: it sees only what its roles and the channel roles allow (opts.roles_mode).
-
Passwords, keys, and tokens are hidden as
*****(masking for mcp channels). -
Other data is provided to the agent as is and passed to the model provider the agent works with: full names, logins, user numbers and email addresses, address book, numbers in call history, request and message texts, product layer data fields, numbers and SIP addresses in call diagrams, for the master domain — server addresses, node names and paths from system state. Limit the channel user roles to the necessary sections and consider personal data processing requirements.
-
The agent receives response content (names, texts, fields) as data, not as instructions.
-
The web server writes a line to the journal for each tool invocation: channel, tool, result (arguments are not written).
Common problems
| Symptom | Cause and solution |
|---|---|
|
No token or it is invalid: not an |
|
Address blocked after a series of invalid tokens (as with password guessing) or a request from a browser with a foreign |
|
More than 120 calls per minute or 4 simultaneous per channel — the agent will retry later |
Response truncated ( |
Large volume: the agent narrows the request ( |
|
The diagram or closure for this call is already being assembled — retry later |
No reference tools |
The reference is not installed on the web server |