MCP server (/mcp/v1)

Overview

The platform web server is a Model Context Protocol (MCP) server: agents and assistants (Claude Code, IDEs, desktop clients) connect to it to work with the platform through tools.

Tools execute platform API requests on behalf of the integration channel user, with their roles and restrictions. Only REST API (/rest/…​, secret fields are masked) and /api commands needed by tools are available (GET, read-only: routing, representation, and normalization tests, trace, registrar, states, hunt, script, conf, esg/active, b2bua/regerror, b2bua/activecalls, lic/read, system/{state,node,nodes,roles,sites,domains,version}); other paths and integration channels (/rest/v1/service/integration_points) — 403. All tools only read data.

Channel preparation, client connection, and examples of questions to the agent — article Working with the platform via an AI agent (MCP).

Connection

Connection endpoint: http(s)://<server>/mcp/v1, Streamable HTTP transport.

Example for Claude Code:

claude mcp add --transport http era http://<server>/mcp/v1 --header "Authorization: Bearer <token>"

Where <token> is the token_local value of the integration channel of type mcp.

Authentication

  • Every request — with the Authorization: Bearer <token> header, the token of an integration channel of type mcp. Tokens of channels of other types, session identifiers, and cookies are not accepted.

  • Channel settings apply: validity period, address restriction (remoteipmask), client certificate.

  • Without a token or with an invalid token — response 401 with the WWW-Authenticate: Bearer header. An invalid token counts as a failed login attempt: after a series of failures the address is blocked, as with password guessing; a blocked address receives 403, and the block is extended.

  • A request with the Origin header (from a browser) is accepted only if Origin matches the server address (scheme, name, port), otherwise 403.

Protocol

  • Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26 (negotiated during initialize).

  • The server does not create sessions (Mcp-Session-Id is not issued): every request is processed independently, on any web server.

  • Requests — POST with a single JSON-RPC message (for version 2025-03-26 — also a batch of up to 100 messages); responses — application/json. GET and DELETE — 405: there are no server notifications or session termination.

  • Methods: initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, prompts/get.

Tools

Tool Purpose API request

model_collections

Sections and classes of the dynamic model at tree level

GET /rest/v1/model/<path>/

class_describe

Class description: storage mode, properties and types, max_limit, partitioning

GET /rest/v1/design/classes

model_query

Reading a class collection: filter, order, mask, offset/limit (up to 200, default 50), countonly, interval, aggr + groupby aggregation

GET /rest/v1/model/<class>

model_get

Class entity by id (partition — for historical classes), mask

GET /rest/v1/model/<class>/[<partition>/]<id>

stat_dictionary

Stat service indicator dictionary (as the era://dict/stat resource)

GET /rest/v1/model/stat/Indicators

config_list

Objects of the domain configuration collection (accounts, rules, routes, providers, scripts, settings, roles…): filter, order, mask, offset/limit, countonly

GET /rest/v1/<collection>

config_get

Configuration collection object by id, mask

GET /rest/v1/<collection>/<id>

route_test

Routing test without a call

GET /api/test/v1/route/apply

representative_test

Representation test (which number and name the callee sees) without a call, domains — the channel domain

GET /api/test/v1/representative/apply

normalization_test

Test of domain provider number normalization (worker domain only); provider login and address hidden

GET /api/test/v1/normalization/apply

calls_recent

Call legs of the last ~20 minutes (without addresses and media)

GET /api/monitor/v1/trace/calls

call_closure

Call closure by callid (master domain only)

GET /api/monitor/v1/trace/closure_total

call_diagram

SIP call diagram as plantuml text (up to 3 minutes)

GET /api/monitor/v1/trace/trn?mode=plantuml

call_activity

Call activity diagram as plantuml text (up to 3 minutes)

GET /api/monitor/v1/trace/activity_diagram?mode=plantuml

registrations

Domain account registrations (without addresses): active, count by domains, unregistered, with missing forks

GET /api/monitor/v1/registrar/{active,count,unregistered,unregistered_forks}

provider_registrations

Domain provider registrations on esg servers: registration state and ping, online trunks (worker domain only; without provider login and address)

GET /api/monitor/v1/esg/active

registration_errors

Recent account registration errors: time, account, user agent, reason, Call-ID (without addresses)

GET /api/monitor/v1/b2bua/regerror

calls_active

Current calls on b2bua servers: state, time, leg Call-ID

GET /api/monitor/v1/b2bua/activecalls

hunt_state

Hunt group state: resources, queue, summary

GET /api/monitor/v1/hunt/{states,abons,info}

user_states

States (presence) of accounts, numbers, users, and voicemail boxes

GET /api/monitor/v1/states/{active,count,details}

scripts_active

Running scripts (svc, ivr)

GET /api/monitor/v1/script/active

license_info

Domain license: limits; for the master domain — products, features, terms

GET /api/admin/v1/lic/read

conferences_active

Active domain conferences and their participants

GET /api/monitor/v1/conf/{rooms,participants}

system_state

System deviation report (master domain only): for each key — a hint and a section of the article System state warnings; level 0–2, keys; one collection per channel

GET /api/monitor/v1/system/state

system_overview

Sites, nodes by servers, microservices by nodes, domains by sites, version (master domain only)

GET /api/monitor/v1/system/{sites,nodes,roles,domains,version}

system_node

State of one node: availability, microservices, CPU, memory, disk, interfaces, queues, hashes (master domain only)

GET /api/monitor/v1/system/node

docs_search

Help search (all words, word forms, phrase in quotes)

—

docs_read

Help page as text by path or uri (as in search results and hints; a section anchor is allowed), long ones in parts (next_offset)

—

  • The tool list (tools/list) contains only those available to the channel: by domain type and roles (IAM) — the same as applied by the tool API (token roles — channel user roles and opts.roles by opts.roles_mode; /api and the model tree — only for a channel with a user); the config_* collection list is narrowed the same way. On call, rights are checked by the API as usual.

  • Collections with scripts, attachments, and free content (uc/ivrscripts, service/svcscripts, service/svctasks, domain/mservices, domain/roleapps, uc/cpd/templates) are unavailable to config_* tools: code and parameters may contain credentials not covered by masking.

  • Arguments are validated against the tool schema; only validated segments from arguments enter the request path (class name, id, collection from the list). An argument error and an API error (code, message, explanation) are returned to the agent as a result with isError.

  • Secret fields — ***** (masking for mcp channels); filtering and sorting by them — error 422.

  • Large responses are truncated: the result contains truncated: true and a hint (next offset — for tools with offset, mask, filter, aggr); an object larger than the allowed size — an error suggesting to select mask fields.

  • Call closure and diagrams are executed one at a time per channel and callid: a repeat while collection is not complete receives the response "already in progress".

  • Help tools are available if help is installed on the web server.

User data (iam/users, address book, etc.) and infrastructure data (server addresses, node names, paths — system_* tools) are provided to the agent as is and passed to the model provider used by the agent. Limit the channel user roles to the necessary sections.

Prompts

  • system_check — system state analysis: collect the report, group warnings by importance, explain what is happening, clarify by nodes and license, suggest actions. Available to a master domain channel with the system_state tool; in Claude Code — the /mcperasystem_check command.

Resources

  • era://docs/index — list of help pages; era://docs/{+path} — help page.

  • era://dict/stat — stat service indicator dictionary (code, name, kind, filter, filter and argument labels, value editor, archive levels) and rules for selecting value collections and counters; rights — as for model_query to stat/Indicators.

Limitations

  • Request body size — no more than 1 MB (413), body transfer — no longer than 15 seconds (408).

  • Content-Type: application/json (otherwise 415); the Accept header, if passed, must allow application/json (otherwise 406).

  • Rate: no more than 120 tool calls and resource reads per minute and 4 simultaneous per channel (on each web server; calls in a batch are counted separately); exceeding — the rate limited response with a retry time. Values are changed by the node parameter ws_mcp_limits (#{rate ⇒ N, parallel ⇒ M}).

  • Call timeouts: 30 seconds; call closure and system state — 60 seconds; diagrams — 190 seconds.

  • The web server log — one line per request: client address, method, tool, domain, channel, result, API response codes, duration, size. Call arguments are not recorded.