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

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

  2. Create an integration channel of type mcp and specify this user (opts.userid). The opts.allow_modify option remains disabled.

  3. Save the channel token (token_local): it is shown in clear text once — on creation and reissue.

  4. 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 — /mcperasystem_check)

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

401

No token or it is invalid: not an mcp channel, reissued, channel expired, address does not pass remoteipmask — check the channel and token

403

Address blocked after a series of invalid tokens (as with password guessing) or a request from a browser with a foreign Origin

rate limited

More than 120 calls per minute or 4 simultaneous per channel — the agent will retry later

Response truncated (truncated)

Large volume: the agent narrows the request (mask, filter, aggregation) or reads the next page

already in progress

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