Yeastar P-Series PBX

Yeastar MCP Server

MCP server for the Yeastar P-Series PBX System OpenAPI - read-only visibility into extensions, extension groups, trunks, inbound/outbound routes, IVR menus, ring groups, queues (including live call/agent status), the company contact directory, call detail records (CDR), call reports, backup metadata, and certificate metadata, for AI assistants and the WYRE Conduit gateway.

Appliance/Edition Scope

This connector targets the P-Series Appliance Edition's OpenAPI, base path `openapi/v1.0`. Per Yeastar's own developer docs (help.yeastar.com, "P-Series Appliance Edition Developer Guide"), the API is only supported on:

• Hardware models P550, P560, and P570 running PBX firmware 37.7.0.16 or later. Other Appliance Edition hardware (e.g. P510) is not documented as supporting the API at all - the docs state functionality "is only supported on P550, P560, and P570" without qualification.
• The docs do not describe any narrower per-endpoint model restriction beyond that - every endpoint this connector implements is covered by the same P550/P560/P570 + firmware-37.7.0.16+ statement.

Cloud Edition is a separate product with its own developer guide and its own OpenAPI surface (same openapi/v1.0 base path structure, firmware requirement documented as 84.7.0.17+), which this connector's request/response shapes were not independently verified against - Appliance and Cloud Edition guides diverge in places (e.g. Cloud Edition additionally documents a v2.0 CDR surface not covered here). If a customer runs Cloud Edition, treat this connector as unverified, not confirmed-incompatible - most of the base OpenAPI mechanics (token exchange, response envelope, pagination) are described identically in both guides, but no endpoint here has been tested against a live Cloud Edition instance.

Software Edition (self-hosted, non-appliance) and any other P-Series variant are out of scope - not mentioned in the Appliance Edition API-support statement above, and not evaluated for this connector.

If a customer's actual hardware/edition is unknown, verify against the PBX web portal (Settings -> About, or the model shown in yeastar_get_system_information) before assuming this connector will work - a PBX outside P550/P560/P570 (Appliance) or Cloud Edition will very likely reject get_token outright with the API feature toggle unavailable in its portal at all.

Authentication

Each Yeastar P-Series PBX is its own appliance, with its own domain/IP and its own credentials - there is no shared hosted API endpoint. A customer enables the API themselves in their PBX's web portal (Integrations -> API, toggle "API" on) and generates a Client ID and Client Secret there. This is not a browser-based OAuth consent flow - the customer pastes the resulting Client ID/Secret directly into the connect form, the same shape as this fleet's other self-hosted/BYO-instance connectors (e.g. Hudu, IT Glue), not the shared-app Authorization Code flow used for SaaS vendors like Cork.

This connector exchanges the Client ID/Secret for a short-lived access token itself - it never proxies them directly into a PBX request. Per Yeastar's docs (POST /openapi/v1.0/get_token), the wire format is genuinely {"username": " ", "password": " "} - Yeastar's own docs are explicit that these fields *are* the Client ID/Secret ("obtain the username from the Client ID on PBX web portal"), not a separate credential; this connector preserves that field naming rather than renaming it, since it's what the vendor's API actually expects on the wire.

Token lifetime and caching. Access tokens expire after 30 minutes; refresh tokens after 24 hours. Yeastar also caps each application to 8 simultaneous valid tokens. Because of that cap, this connector does not mint a fresh token on every tool call - src/client.ts caches the access token in memory, keyed by appliance + Client ID + Client Secret, and reuses it across calls until it's within 60 seconds of expiring. On a TOKEN EXPIRED response (errcode 10004), it transparently mints a fresh token and retries the failed call exactly once. This is a deliberate deviation from the pattern in this fleet's other connectors (which mint per-request or hold a single static key) - it exists because Yeastar's token model genuinely requires it, not as an optimization for its own sake: without caching, any session making more than 8 tool calls within a 30-minute window would start failing with MAX LIMITATION EXCEEDED (errcode 60002) from Yeastar itself.

In gateway mode, the three credential fields arrive per-request via X-Yeastar-Pbx-Domain / X-Yeastar-Client-Id / X-Yeastar-Client-Secret headers, injected by the Conduit gateway. A /mcp request missing any of those headers is rejected with 401 and does not fall back to YEASTAR_* in the process environment. In local/stdio mode, and in HTTP AUTH_MODE=env, they're read from YEASTAR_PBX_DOMAIN / YEASTAR_CLIENT_ID / YEASTAR_CLIENT_SECRET.

HTTP also requires service-to-service auth. With CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The header value is t= ,v1= . The MAC is HMAC-SHA256 over the ASCII message t= (the same t= prefix that appears in the header), keyed by CONDUIT_S2S_SECRET, and encoded as lowercase hex. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401 before vendor credentials are read. The secret is never written to logs. /health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

Request limits

• HTTP request bodies are capped at 256 KiB (262144 bytes). After the X-Gateway-S2S check passes (and, in gateway mode, the X-Yeastar-* credential headers are present), a Content-Length above the cap returns 413 with a JSON-RPC error; bodies without Content-Length are capped by the MCP SDK transport. Unauthenticated requests still get 401 first.
• tools/call arguments are capped at 10,000 elements (every array item and object key at any depth). Larger inputs return a fixed isError tool result ("Tool input exceeds the maximum of 10000 elements") that does not echo the tool name, and are never dispatched.

These limits address CVE-2026-111768 / GHSA-46jr-4wx8-v453 (memory exhaustion during validation) and GHSA-f897-62hf-6gxq (no request body / batch cap).

Every request also passes a mandatory `User-Agent: OpenAPI` header - Yeastar's API rejects requests missing it (errcode 40002, "PARAMETER ERROR").

Defensive field-stripping. Trunk configuration commonly carries SIP registration secrets (auth/register passwords) inline in the same object a read returns, and Yeastar's schema for these objects isn't machine-verifiable from the docs alone. Every response from every tool in this connector - not just trunk tools - passes through stripSecretFields() before it ever reaches the model: any object key matching /secret|password|pwd/i, at any depth, is dropped. This is a blanket safety net on top of, not instead of, the endpoint-level exclusions below (extension/getpassword and conference/viewpassword are never called at all).

Credential-scope finding

Structurally verified (this codebase): this connector's src/client.ts implements exactly one HTTP verb function, doGet - there is no doPost/doPut/doDelete anywhere in this codebase, so it is *incapable* of issuing a write/control/delete request to the PBX regardless of what the credential itself is permitted to do. src/__tests__/tool-scope.test.ts pins the exact 26-tool set and asserts no tool name matches a write/control/credential-exposing token list.

Vendor-documented, not independently verified: whether the PBX's own admin portal offers any way to scope a Client ID/Secret pair to read-only access is not documented. Per help.yeastar.com's "Enable Yeastar P-Series PBX API" page, enabling the API surfaces exactly one toggle ("API" on/off) plus an optional IP-restriction allowlist and status-monitor configuration - no permission-group, role, or scope selection is described anywhere in that flow. This differs from e.g. Cisco Duo (cisco-duo-mcp), where the vendor's own admin panel offers explicit Grant Read Resource / Grant Write Resource toggles per integration. The practical implication: a Client ID/Secret pair generated for this connector is, as far as Yeastar's own documentation shows, capable of the PBX's full write/control API even though this connector's code never exercises that capability. The only vendor-side compensating control documented is the optional IP-restriction allowlist (scope the credential to only be usable from Conduit's egress IP(s)) - recommend enabling it. If a narrower credential-scoping mechanism does exist and simply isn't documented publicly, it wasn't found during this connector's build and should be treated as unconfirmed.

Configuration

Tools

All 26 tools are read-only. yeastar_get_trunk is additionally classified sensitive in Conduit's VENDOR_TOOL_CONFIG given trunk config's proximity to telephony secrets, even after field-stripping.

System

• yeastar_get_system_information - this appliance's model, firmware version, hostname.
• yeastar_get_system_capacity - current usage against licensed extension/trunk/concurrent-call capacity.

Extensions

• yeastar_list_extensions - list extensions with basic info and per-device online/presence status.
• yeastar_get_extension - full detail for a single extension (never includes its password).

Extension Groups

• yeastar_list_extension_groups - list extension groups.
• yeastar_get_extension_group - full detail (member extensions) for one group.

Trunks

• yeastar_list_trunks - list configured trunks.
• yeastar_get_trunk - full detail for a single trunk, with secret-shaped f