Skip to main content

MCP: connect AI assistants

MonoPbx has a built-in MCP server. MCP (Model Context Protocol) is the open standard AI assistants such as Claude Desktop, Claude Code and other MCP clients use to reach outside tools. Once a user connects an assistant, they can ask it things like "who called me this morning?", "summarize my new voicemail", "how did the Sales queue do today?" or "add Ana Ruiz to the phonebook", and the assistant answers with live data from your phone system.

The assistant always acts as the user who connected it, with no more rights than that user has, and only with the permissions the user granted it. Every tool call is written to the company's audit log.

This page is for administrators and users who connect assistants. The list of tools, with the permission each one needs, is on MCP tool reference.

What you need​

  • Nothing to install or switch on: the MCP server is part of every MonoPbx install. It answers at your company's web address followed by /mcp, for example https://pbx.example.com/mcp.
  • A user account in the company. The assistant can only use what that user's roles allow.
  • An MCP client that supports the Streamable HTTP transport with OAuth (most current clients do), or that can send an API key as a bearer token.
  • AI does not have to be switched on for the company to use MCP. The company's own AI tools (see AI tools, connectors and knowledge) are only offered to MCP clients when an owner exposes them.

Connect an assistant (OAuth)​

OAuth is the recommended way: the user signs in with their own MonoPbx account, sees what the assistant asks for and approves it. No password or key is copied into the assistant.

Claude Desktop and claude.ai​

  1. Open Settings > Connectors and choose Add custom connector.
  2. Enter a name (for example MonoPbx) and the server URL https://pbx.example.com/mcp.
  3. Choose Connect. A browser window opens the MonoPbx sign-in page; sign in as usual (with two-factor authentication if your account uses it).
  4. The consent page lists the permissions the assistant asks for. Permissions you do not hold are shown but cannot be granted. Choose Allow.
  5. Back in the assistant, the MonoPbx tools are listed. Turn on the ones you want to use.

Claude Code​

claude mcp add --transport http monopbx https://pbx.example.com/mcp

Then run /mcp inside Claude Code, pick monopbx and choose Authenticate. The browser opens the same sign-in and consent pages as above.

Other MCP clients​

Point the client at https://pbx.example.com/mcp. A standard client then does the rest by itself:

  1. It calls the server without a token and gets 401 with a WWW-Authenticate header that names the server's metadata at /.well-known/oauth-protected-resource/mcp.
  2. It reads that document and the authorization server's metadata at /.well-known/oauth-authorization-server.
  3. It registers itself at /oauth/register (a public client; redirect addresses must be https://, or http:// on 127.0.0.1, localhost or [::1]), or uses the address of its own client metadata document as its client ID.
  4. It opens /oauth/authorize in the browser with PKCE (S256), the scopes it wants and resource=https://pbx.example.com/mcp. The user signs in and approves on the consent page.
  5. It exchanges the code at /oauth/token, refreshes with the refresh token (a new refresh token is issued on every refresh) and can revoke at /oauth/revoke.

Access tokens last 10 minutes and are only valid at the /mcp address of the company they were issued for. Refresh tokens last 30 days and are replaced on every use; presenting an old refresh token again revokes the whole authorization.

Scripts and integrations: API keys​

A script or a server-side integration can use an API key instead of OAuth: create one under Admin > API keys with only the permissions it needs, and send it as Authorization: Bearer <API key>. The key's permissions are the same keys as the scopes below. A key acts as the user who created it; keep it in a secret store and remove it when it is no longer needed.

A web sign-in session cannot be used at /mcp.

Scopes: what an assistant may do​

Scopes are MonoPbx permission keys, the same ones roles use (see Users and roles). The assistant asks for scopes, the user approves them, and on every request the assistant gets the intersection of:

  • the scopes the user approved, and
  • the permissions the user holds right now (a removed role or a disabled account takes effect on the next request).

Good to know:

  • An assistant that asks for no scope at all gets the read-only permissions (those ending in :read) the user holds. It cannot change anything.
  • A few tools can be opened by either of two permissions, exactly like the matching REST call (for example `users:write` or `team:status`); holding one of them is enough. The tool reference lists both.
  • Write tools need their write permission by name, so the user sees it on the consent page. Placing calls needs self:call and sending SMS needs messaging:write through MCP, even though the user can do both in the apps without them.
  • Department limits apply as in the console: a department administrator's assistant only sees and changes that department.
  • tools/list only shows the tools the connection may call. Calling another tool answers 403 with insufficient_scope and the scope to ask for.
  • Team chat (rooms, messages, pins, reactions, live locations, GIFs) is for signed-in people only and is not available through MCP.

Limits​

To stop an assistant that misreads something from repeating an action in a loop, each connection (one OAuth authorization or one API key) has daily limits, counted per UTC day:

WhatLimit per connection and UTC dayWhen it is reached
SMS sent with sendSms100 messages (the company can set its own number on the SMS and MMS limits and costs page, /admin/sms/metering; failed messages do not count)429 MPBX-MCP-SMS-CAP-REACHED; the company's alert addresses get one notice a day
Jira writes (createJiraTicket, addJiraComment, updateJiraIssue, createJiraIssue)50 together, or the company's own number429 MPBX-MCP-WRITE-CAP-REACHED
Every other write tool (phonebook, statuses, agent presence, campaign contacts, integration checks, receptionist setup, the company's own AI tools)200 together, or the company's own number429 MPBX-MCP-WRITE-CAP-REACHED

Administrators with settings:write set the company's own Jira and write limits under Admin > MCP access > Daily write limits (1 to 10000 each; through the API: GET and PUT /api/v1/mcp/write-caps with If-Match). A new limit applies from the next call; what a connection already used today still counts.

A refused call is recorded in the audit log as denied. The limits hold even when an assistant sends many calls at once. The company's own SMS caps, the API's rate limits and each custom AI tool's own rate limit apply as well.

Other limits: one request body is at most 256 KB, and a tool answer larger than 1 MB is refused rather than cut (ask for a smaller page with the limit argument). Lists are paged with limit and cursor.

Changing a stored record​

Changes to a stored record (for example updatePhonebookContact) must say which version they change, as in the REST API. Every tool answer that has a version carries it as ETag: "v3" (also in the result's _meta["mpbx/etag"]). The assistant sends that text back as the if_match argument. If someone changed the record in between, the call answers 412 and the assistant reads the record again.

Audit log​

Every tool call is recorded as mcp.tool_call in the audit log (Admin > Audit log, /admin/audit-log, channel MCP), with the tool name, the HTTP status and the outcome (success, denied or error), and the connection that made it. A call that cannot be recorded returns no data. The OAuth steps are recorded too: client registered, consent granted, token issued and refreshed, authorization revoked, and refused or replayed codes and refresh tokens. Your SIEM export receives the same records (see SIEM export).

Revoking access​

  • Users see the assistants they authorized on the consent page without parameters (https://pbx.example.com/oauth-consent) and can revoke any of them.
  • Administrators open Admin > MCP access to see every user's authorizations (client, user, scopes, when authorized, last used) and Revoke any of them; this needs api_keys:write. Revoking takes effect on the assistant's next request.
  • Disabling a user, or removing a role, takes effect on that user's assistants at once.
  • Remove an API key under Admin > API keys.

Under Admin > MCP access > New clients, administrators with settings:write can turn self-registration of new MCP clients off (clients already registered keep working) and limit the hosts new clients may redirect to.

Security notes for administrators​

  • Text from outside is untrusted. Caller names, voicemail transcripts, SMS bodies, contact notes, Jira issues and web pages are written by people outside your company. Tool answers that hold such text start with an UNTRUSTED CONTENT note telling the assistant to treat it as data, never as instructions. Even so, an assistant can be misled ("prompt injection"). Grant write scopes only to assistants that need them.
  • Keep confirmations on. Use a client that asks before every tool call that changes something (most do for tools not marked read-only) and keep that setting on. The descriptions of write tools tell the assistant to confirm with the user first.
  • Custom AI tools that ask for confirmation are enforced by the server. The first call only returns a read-back and a one-time confirmation_token; nothing is sent. The tool runs only when the same connection repeats the exact call with that token within 10 minutes. A token used once, expired, or sent with other arguments is refused and nothing is sent.
  • Prefer read-only. For summaries and look-ups, approve only the read scopes.
  • Nothing secret comes back. Tools never return passwords, SIP credentials, API keys, provider keys, integration secrets or recording download links. Administration of users, roles, keys, trunks, settings and backups is not available through MCP.
  • Signed client identities. A client that publishes signing keys in its metadata document must prove it holds them on every token request.
  • Watch the audit log for unexpected calls, SMS or changes, and revoke the authorization if an assistant acted on text it read rather than on the user's request.

Troubleshooting​

What you seeWhyWhat to do
The browser says "unknown client_id, or redirect_uri is not registered for it"The client changed its redirect address, or it was removedRemove the connector in the assistant and add it again
Registration answers 403 access_denied (MPBX-OAUTH-REGISTRATION-DISABLED)Self-registration is off for the companyAsk an administrator to turn it on under Admin > MCP access, or to register the client
Registration answers invalid_redirect_uri (MPBX-OAUTH-REDIRECT-HOST-NOT-ALLOWED)The company limits redirect hostsAsk an administrator to add the client's host
The consent page says none of the scopes can be granted (MPBX-OAUTH-INVALID-SCOPE)You hold none of the permissions the assistant asks forAsk for a role that has them, or connect with fewer scopes
A tool is missing from the assistant's listThe connection lacks its permission, or you lost a roleReconnect and approve the scope, or ask an administrator
A call answers 403 with insufficient_scopeThe tool needs a scope this connection does not haveReconnect and approve that scope
A call answers 401 and the assistant asks you to sign in againThe authorization was revoked, the refresh token expired after 30 days unused, or your account was disabledConnect again
429 MPBX-MCP-SMS-CAP-REACHED or MPBX-MCP-WRITE-CAP-REACHEDThe connection reached its daily limitWait for the next UTC day, do it in the console or the app, or ask an administrator to raise the company's limit
A custom AI tool answers confirmation_invalidThe confirmation_token was used already, expired (10 minutes), belongs to another connection, or was sent with other argumentsCall the tool again without the token, show the new read-back to the user and repeat with the new token
412 on a changeThe record changed since the assistant read itLet the assistant read it again and retry
"the API's answer is larger than an MCP tool result may be"The answer is over 1 MBAsk for fewer rows (limit)
A browser-based client gets 403 "cross-origin MCP requests are refused"The page calling /mcp is on another web addressUse a desktop or server-side client

Error codes are listed in API error codes.