ringcentral-mcp

RingCentral MCP Service — a stateless HTTP MCP server wrapping the RingCentral REST API, covering account info, extensions, phone numbers, presence, call queues, contacts, and call logs/recordings.

Tech stack: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

What is RingCentral / when would an agent use this

RingCentral is a cloud phone / UCaaS (telephony) platform MSPs use to manage a customer's business phone system — extensions, phone numbers, presence, call queues, directory/personal contacts, and call history. An agent should reach for this MCP for requests like:

• "Who has extension 101 / what extensions exist?" → ringcentral_list_extensions, ringcentral_get_extension

• "Is this person available / on a call right now?" → ringcentral_get_presence

• "Which numbers are provisioned for this account?" → ringcentral_list_phone_numbers

• "Who staffs the support call queue?" → ringcentral_list_queues, then ringcentral_list_queue_members

• "Show recent inbound calls for extension X" / "get that call's recording" → ringcentral_list_user_call_log / ringcentral_list_company_call_log, then ringcentral_get_call_recording using the call log entry's recording.id

It follows the MSPbots Vendor MCP Service SOP: stateless, no stored credentials, per-request header authentication. All 13 tools are read-only.

Related MCP server: Sentinel Core Agent

Authentication

RingCentral's REST API uses the JWT bearer flow — a server-to-server grant with no user browser redirect. A JWT credential is generated in the RingCentral admin console for a dedicated "service user" (Roles & Permissions → the service user's JWT credential), then exchanged for a short-lived access token:

POST https://platform.ringcentral.com/restapi/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<jwt>

A fresh access token is cheap to obtain and this service must stay stateless, so it re-authenticates on every call rather than caching/refreshing a token — no derived token is ever cached across requests (SOP §3.4).

Credentials are read from HTTP headers only, on every request — never from environment variables. There is no local/single-tenant fallback mode; this keeps one tenant's credentials from ever leaking into another tenant's request.

授权参数说明 (Authentication headers)

Every request to /mcp must include the following HTTP headers:

Missing any of the three headers returns 401 Unauthorized with a required_headers list in the body.

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m ringcentral_mcp

Health Check

curl http://localhost:8080/health
# {"status": "ok"}

No credentials are required for the health endpoint (it is a pure local liveness probe and never calls the RingCentral API).

Environment Variables

No credential fields exist in configuration — see Authentication above.

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP)

• Headers: X-RingCentral-Client-Id, X-RingCentral-Client-Secret, X-RingCentral-Jwt (all required)

Available Tools (13)

page/per_page on list tools: this server caps per_page at 200 regardless of the higher limits some RingCentral endpoints document (call-log endpoints allow up to 1000, directory/entries up to 2000) — 200 is the stricter of "our SOP ceiling" vs. "vendor's real max" in every case here, so 200 always governs. per_page is otherwise passed straight through to RingCentral's own perPage query parameter.

测试示例 (Test Example)

{
  "method": "tools/call",
  "params": { "name": "ringcentral_list_extensions", "arguments": {} }
}

Equivalent curl against the running server (streamable HTTP MCP endpoint):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-RingCentral-Client-Id: <client_id>" \
  -H "X-RingCentral-Client-Secret: <client_secret>" \
  -H "X-RingCentral-Jwt: <jwt>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "ringcentral_list_extensions", "arguments": {} }
  }'

API Reference

• RingCentral API Reference

• JWT Auth Flow

• Per-page limits verified against RingCentral's own OpenAPI spec (assets-developers.ringcentral.com/dpw/api-reference/specs/public/office/rc-platform.yml): the generic perPage parameter (extensions, phone numbers, queues, queue members, contacts) has no documented maximum; call-log endpoints document a documented max of 1000; directory/entries documents a max of 2000. This server's own 200 hard cap is stricter than all of these, so it is always the binding limit.

Known Gaps / Implementation Notes

• ⚠️ Not yet tested against a live RingCentral account. All 13 tools have been checked structurally only (MCP handshake, tools-list, schema validity, /health, gateway 401 credential-gating). Per the parent ClickUp task, this is currently blocked at the business/procurement level — MSPbots has never purchased a RingCentral service (no paid user seat), and a JWT credential can only be bound to a real service user account, so no test credentials are available yet.

• Endpoints verified directly against RingCentral's official OpenAPI spec — not guessed.

• ringcentral_get_call_recording/ringcentral_download_call_recording: there is no standalone "list all recordings" endpoint — recording IDs must come from a call-log entry's recording.id field (query call logs with recordingType/withRecording params to surface them). ringcentral_download_call_recording cannot return actual audio bytes (not representable as MCP tool text output) — it returns content-type/size only; use ringcentral_get_call_recording's contentUri field for an actual download URL.

• "Queues" have no separate /call-queue resource type in RingCentral's model — they're extensions with type Department/Call Queue, exposed at the dedicated /call-queues paths used here.

• Scope is limited to the 13 operations above, not RingCentral's full API surface (which also includes messaging/SMS, meetings, fax, call control/RingOut, and account provisioning).

• This server only runs in HTTP/gateway mode (no stdio transport, no single-tenant env-var credential mode) — the SOP requires credentials to come exclusively from per-request headers, so a code path that reads them from the environment instead was removed rather than kept as a "local dev convenience."