Pexip Infinity MCP Server

MCP (Model Context Protocol) server for the Pexip Infinity Management API. It gives an LLM-based agent everything it needs to manage and operate a Pexip Infinity deployment, exposing 122 curated tools and covering all four admin API categories: Configuration, Status, History, and Command.

Disclaimer: This is an independent, community-built project. It is not affiliated with, endorsed by, or sponsored by Pexip. It uses Pexip's public Management API and sends no telemetry or analytics. The server needs no external network access beyond the Pexip Management Node you configure, plus your own identity provider if you choose to use OIDC. It never sends your data anywhere else.

Quick start

You'll need your Pexip Management Node hostname plus credentials. OAuth2 is recommended for production; basic auth (admin username + password) is recommended only for dev/lab environments. See Configuration to set up an OAuth2 client.

The server starts read-only by default: it can list and report, but every create / update / delete / control tool is removed from the catalog until you explicitly enable writes. Connect first, confirm it works, then decide.

① Claude Desktop: one-click install

The simplest path: no terminal, no JSON.

1. Download the .mcpb bundle for your OS (macOS or Windows) from the latest release.

2. Double-click it. Claude Desktop opens an install dialog showing the server and the permissions it requests.

3. Fill in the form with your Management Node host and either an OAuth2 client (recommended) or an admin username + password (dev/lab only). Leave read-only on. Click install.

4. Try it. Ask Claude: "List the VMRs on my Pexip node" or "Show me the Pexip system status."

To enable writes later, edit the server in Claude Desktop's settings and turn read-only off.

② Manual config: Claude Code & other MCP hosts

For Claude Code, Cursor, or any MCP host that takes a JSON server config.

1. Install the server (needs Python 3.11+):

git clone https://github.com/Josh-E-S/pexip-mgmt-mcp.git
cd pexip-mgmt-mcp
pipx install .          # installs the `pexip-mgmt-mcp` command on your PATH

2. Add it to your MCP host by pointing its config at the pexip-mgmt-mcp command. Use OAuth2 for production:

{
  "mcpServers": {
    "pexip-mgmt": {
      "command": "pexip-mgmt-mcp",
      "env": {
        "PEXIP_HOST": "pexip-mgr.example.com",
        "PEXIP_AUTH_MODE": "oauth2",
        "PEXIP_OAUTH2_CLIENT_ID": "your-client-id",
        "PEXIP_OAUTH2_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
      }
    }
  }
}

For dev/lab, use basic auth instead: swap the PEXIP_AUTH_MODE / PEXIP_OAUTH2_* keys for "PEXIP_USERNAME": "admin" and "PEXIP_PASSWORD": "...". See Configuration for all options.

• Enable writes: add "PEXIP_READ_ONLY": "false" to env (read-only is the default).

• Claude Code shortcut (instead of hand-editing JSON):

  # OAuth2 (recommended for production)
  claude mcp add pexip-mgmt \
    -e PEXIP_HOST=pexip-mgr.example.com \
    -e PEXIP_AUTH_MODE=oauth2 \
    -e PEXIP_OAUTH2_CLIENT_ID=your-client-id \
    -e PEXIP_OAUTH2_PRIVATE_KEY="$(cat oauth2_private_key.pem)" \
    -- pexip-mgmt-mcp
  
  # basic auth (dev/lab only)
  claude mcp add pexip-mgmt \
    -e PEXIP_HOST=pexip-mgr.example.com \
    -e PEXIP_USERNAME=admin \
    -e PEXIP_PASSWORD=... \
    -- pexip-mgmt-mcp

Other ways to run

• Docker (self-hosted HTTP transport): run the container alongside your Infinity, serving on 127.0.0.1:8000. For lab/dev, fronting it with a tunnel or proxy is fine. For production, run it as a proper service behind a hardened reverse proxy (TLS, authentication, access control) on a managed host, not a dev tunnel. See DEPLOY.md.

• From source (developers): clone the repo, then:

  pip install -e .
  cp .env.example .env          # edit with your Management Node details
  python -m pexip_mcp --healthcheck
  # OK: connected to pexip-mgr.example.com as admin, schema fetched

  See Testing for the full dev workflow.

Related MCP server: Packet Tracer MCP

Contents

• Quick start

• Coverage

• How it fits together

• Examples

• Configuration

• Quality: the eval suite

• Skills SDK

• Testing

Coverage

The full catalog with per-tool annotations and parameters is in TOOLS.md (regenerate with uv run python scripts/generate_tools_md.py).

This MCP server is designed to optimize tool use. High-traffic resources (VMRs, users, devices, rules) get dedicated typed tools; the ~70 remaining configuration resources share five generic CRUD tools backed by a resource registry. That keeps the catalog at 122 tools, which lowers per-request token use and improves the agent's tool selection (verified by the eval suite).

How it fits together

Source layout:

src/pexip_mcp/
├── client.py                 # Async PexipClient (all 4 API categories), 429-aware retry
├── config.py                 # PexipSettings (env-driven, pydantic-settings)
├── mcp_app.py                # FastMCP instance + lifespan
├── server.py                 # Imports tool modules to trigger registration
├── __main__.py               # Entry point + --healthcheck + --http
└── tools/
    ├── _helpers.py           # get_client, resolve_id_by_field, paginate_all, annotation presets
    ├── command.py            # Active call control + name→UUID resolvers
    ├── status.py             # Live state + per-participant quality
    ├── history.py            # CDRs + summarize_calls aggregation
    ├── resource_crud.py      # Generic CRUD + resource registry (~70 resources)
    ├── schema.py             # Live schema introspection
    └── conference.py, end_user.py, device.py, gateway_rule.py, alias.py,
        automatic_participant.py, infrastructure.py, ldap.py,
        ivr_theme.py, global_settings.py   # dedicated typed CRUD per resource

Examples

Real Claude Desktop conversations against a lab Pexip node.

A status question, answered directly:

Config inventory across multiple resources in one ask:

CDRs turned into an interactive dashboard, not a data dump:

Configuration

All env vars are PEXIP_* prefixed and loaded from .env (or the process environment). See .env.example for an annotated template.

Read-only mode (default)

The server runs in read-only mode by default: only the read tools (list / get / schema) are exposed. Every create, update, delete, and Command-API control tool is removed from the catalog at startup, so the LLM cannot mutate the deployment even if it tries. This is enforced server-side: the tools are gone from the catalog, not merely flagged with an advisory readOnlyHint.

To enable the mutating admin surface, set PEXIP_READ_ONLY=false (logged loudly at startup). Even then, generic CRUD refuses to touch security-critical resources (SSH keys, admin roles/permissions, authentication/SSO, TLS/CA certs) unless you also set PEXIP_ALLOW_SECURITY_RESOURCES=true. Pair writes with a least-privilege Pexip Administrator Role for defense in depth.

Authentication: OAuth2 vs basic

Two modes, selected by PEXIP_AUTH_MODE:

• oauth2 (recommended for production): an OAuth2 JWT bearer assertion (ES256). The server signs a short-lived JWT with the client's private key and exchanges it at https://<host>/oauth/token/ for a 1-hour bearer token (cached and auto-refreshed). It authenticates once per hour instead of on every request and keeps a reusable admin password out of the server's environment.

• basic (dev/lab only): a local Management Node admin username + password. Works out of the box on every Infinity deployment and is the quickest way to get started, but sends admin credentials on each request. Not recommended for production.

Set up an OAuth2 client in the Pexip admin UI under Users & Devices > OAuth2 Clients: add a client, then copy its Client ID and Private key (the private key is shown only once). You also enable Management API OAuth2 and attach an Administrator Role, per Pexip's Managing API access via OAuth2. Then set PEXIP_AUTH_MODE=oauth2, PEXIP_OAUTH2_CLIENT_ID, and PEXIP_OAUTH2_PRIVATE_KEY.

Quality: the eval suite

The evals/ suite measures whether an LLM can drive these tools correctly from natural language. It defines 156 scenarios written as real admin requests ("mute all the guests in AllHands", "point the syslog server at 10.0.0.99"), graded automatically across three layers:

Scoring supports exact / subset / ordered-subset / any-of tool matching, per-step parameter checks with acceptable-alternative values, and optional steps for chains where server-side name resolution makes a lookup legitimate but unnecessary. See evals/README.md for the case format and how to add scenarios.

Current state: the full suite passes: 698 passed, 12 skipped, 0 failures across all four layers (208 unit + 332 deterministic eval checks + LLM-graded + 33 live), 86% coverage. The 12 skips are env-gated live cases (e.g. no dial target set). Reproduce the full run with uv run pytest tests/ evals/ --llm --live, or the free deterministic subset (540 checks) with uv run pytest tests/ evals/.

Skills SDK

pexip-mgmt-skills/ is a self-contained Agent Skills (open standard) + Claude Code plugin package that wraps this MCP server with operator runbooks and developer-reference skills. Built to be extractable: cp -r pexip-mgmt-skills/ out and you have a complete, plug-installable SDK that loads in Claude Code, Gemini CLI, Codex CLI, Cursor, or any other compliant host.

Currently ships 9 skills across 6 domains:

See pexip-mgmt-skills/README.md for the install instructions and pexip-mgmt-skills/ARCHITECTURE.md for the design rules. The companion awesome-pexip-skills covers the client-side (webapp3, @pexip/infinity, @pexip/media). Install both for full Pexip coverage.

Testing

uv run pytest                  # 208 unit + 332 deterministic eval checks, 86% coverage
uv run pytest tests/           # 208 unit tests (mocked HTTP via respx), ~2s
uv run pytest evals/           # 332 deterministic eval checks, free
uv run pytest evals/ --llm     # LLM-graded evals (needs ANTHROPIC_API_KEY, ~$2)
uv run pytest evals/ --live    # integration against a real node (needs .env)
uv run ruff check src tests evals

Every run prints a coverage report, but the 80% gate is enforced only in CI on the full suite (--cov-fail-under=80 in .github/workflows/ci.yml), so subset runs like uv run pytest evals/ show partial coverage without failing. Unit tests mock the Pexip Management API with respx; the retry suite monkeypatches asyncio.sleep so backoff tests run instantly.

License

MIT