MediaSFU

MediaSFU MCP Integration Toolkit

The official MediaSFU MCP toolkit helps developers and MCP-capable agents plan, scaffold, diagnose, and harden MediaSFU frontend and backend integrations.

Run the stdio server directly with npm:

npx -y @mediasfu/mcp-sdk-tools

For repeatable MCP client configuration, pin the supported major version:

{
  "mcpServers": {
    "mediasfu": {
      "command": "npx",
      "args": ["-y", "@mediasfu/mcp-sdk-tools@1"]
    }
  }
}

On Windows, use npx.cmd if the MCP client does not resolve the npm shim. You can also install globally and run the explicit executable:

npm install --global @mediasfu/mcp-sdk-tools@1
mediasfu-mcp

The mediasfu-mcp-http executable starts the optional local Streamable HTTP transport. See LOCAL_MCP_SETUP.md for client examples.

Act on your own account (account mode)

mediasfu-mcp-account lets your assistant create and end rooms, place AI-agent and SIP calls, list recordings, set your room webhook and read balance and usage, using your MediaSFU API key. It runs locally over stdio; the key stays in your MCP client's environment, is sent only to https://mediasfu.com, and is redacted from every tool result.

{
  "mcpServers": {
    "mediasfu-account": {
      "command": "npx",
      "args": ["-y", "-p", "@mediasfu/mcp-sdk-tools@1", "mediasfu-mcp-account"],
      "env": {
        "MEDIASFU_API_USERNAME": "<api username>",
        "MEDIASFU_API_KEY": "<api key>"
      }
    }
  }
}

Get both values at mediasfu.com/api-keys. Start with a sandbox key: rooms beginning with s are sandbox, p are production.

Read tools run immediately. Anything that creates, changes, calls or ends returns confirmation_required with a preview until the assistant calls it again with confirm: true, so you approve every billable or destructive step.

Supported SDK surfaces

• shared runtime and backend integration
• ReactJS
• Angular
• React Native
• React Native Expo
• Vue
• Flutter
• Kotlin / Android / KMP
• Swift / Apple platforms
• Unity

The default public surface exposes 159 integration tools. Thirty-three documentation-build and parity tools are internal; set MCP_INCLUDE_INTERNAL_TOOLS=1 only in a trusted local maintainer workspace to expose the full 192-tool surface.

Core tools

Every SDK provides:

• sdk.recommend
• app.scaffold
• integration.plan
• env.preflight
• room.bootstrap
• feature.map
• runtime.diagnose
• fix.suggest
• api.reference.search
• room.flow.explain
• ui.mode.recommend
• ui.overrides.guide
• security.proxy.rooms

The shared surface adds production patterns derived from MediaSFU's headless, widget, telephony, and AI call-control integrations:

• shared::frontend.architecture.plan
• shared::headless.integration.plan
• shared::widget.integration.plan
• shared::telephony.call-control.plan
• shared::solution.capsule.plan
• shared::external-media.integration.plan
• shared::participant-control.integration.plan
• shared::room.lifecycle.plan
• shared::embedded.layout.plan
• shared::room.authority.plan
• shared::product.pattern.plan
• shared::custom-recording.scene.plan
• shared::runtime.readiness.diagnose
• shared::lifecycle.cleanup.audit
• shared::credential.broker.plan
• shared::backend.integration.guide

The widget planner distinguishes the six standalone custom elements, plain script delivery, modular npm imports, and the optional React/headless entries. It also returns the reviewed package state so package publication and hosted delivery are never mistaken for complete live-runtime evidence.

Tool names use sdkId::toolId, for example reactjs::integration.plan.

Capability evidence and SDK freshness

sdk-registry.json records the detected package name/version, manifest and reference hashes, and per-SDK evidence topics. feature.map returns this as sdkRelease and capabilityEvidence.

Evidence status is intentionally conservative:

• documented means the capability is evidenced in the bundled SDK reference.
• not-evidenced means the bundled reference does not prove it; it does not claim the SDK cannot support it.

npm run registry:check fails when a manifest, bundled reference, live package version, canonical package path, or evidence profile drifts. It also fails when a discoverable MediaSFU SDK workspace is not registered. Maintainers refresh reviewed changes with npm run registry:write.

feature.map also returns the canonical language-neutral operation IDs, evidence status vocabulary, exact SDK coverage identity, and security boundary. The MCP registry stores one hash-bound catalog reference and one compact hash-bound runtime-contract reference. The latter records the runtime registry schema, required stable contract IDs, complete contract-ID list, source path, and SHA-256 without copying the per-SDK evidence rows. Custom recording scenes are described in the canonical custom recording guide; the MCP surface exposes the ordinary recording lifecycle and points adopters to that guide for the portable scene contract and server-owned completion rules. The canonical product-pattern index and starter catalog link runnable Familiar Calls, Live Auction, Watch Together, Agents, VOIP, and SpacesTek references to their independently qualified platform evidence. The lifecycle, layout, authority, product-pattern, and custom-recording planners expose those contracts without treating application composition or shared-core exports as cross-SDK proof. Run npm run catalog:check locally to detect operation, coverage, security, or runtime-contract drift.

Safe scaffolding

Scaffolding is a dry run unless apply: true is explicit. Apply mode:

• resolves from projectRoot, defaulting to the MCP process working directory;
• writes only below a relative outputDir, defaulting to mediasfu-generated/sdkId;
• rejects path traversal;
• refuses existing files unless overwrite: true;
• emits MEDIASFU_INTEGRATION.md with the detected SDK release and runtime checklist;
• never emits long-lived credential placeholders.

ReactJS emits production-pattern TypeScript/React starters based on the live MediaSFU frontend's headless runtime model. Other SDKs emit version-aware implementation recipes where the package API has not been compile-verified by this Node release process. This avoids presenting speculative source as compile-ready code.

Example:

node ./scripts/mcp-engine.mjs run reactjs app.scaffold --input '{"apply":true,"projectRoot":"/path/to/app","outputDir":"src/mediasfu"}'

Obtain scoped room/session material from an authenticated backend. Never put a long-lived MediaSFU API key in browser storage, mobile preferences, source code, logs, or a shipped desktop/mobile/game binary.

Run locally

npm install
npm run validate
npm run registry:check
npm run mcp:server:selftest
npm run mcp:http:selftest
npm run release:check

Useful examples:

node ./scripts/mcp-engine.mjs list reactjs
node ./scripts/mcp-engine.mjs run reactjs integration.plan --input '{"appType":"meeting"}'
node ./scripts/mcp-engine.mjs run reactjs api.reference.search --input '{"query":"create room"}'
node ./scripts/mcp-engine.mjs run reactjs feature.map --input '{"requestedFeatures":["conference","screen-share"]}'
node ./scripts/mcp-engine.mjs run shared frontend.architecture.plan --input '{"mode":"auto","needsWidget":true}'

MCP transports

Stdio entry point: scripts/mcp-stdio-server.mjs.

Streamable HTTP entry point: scripts/mcp-http-server-v2.mjs. It exposes public read-only tools at /mcp and scoped MediaSFU account actions at /mcp/actions.

The stdio and public HTTP tool surfaces are read-only by default. Local filesystem/command side effects require MCP_ALLOW_LOCAL_SIDE_EFFECTS=1 and must never be enabled on a shared endpoint.

The hosted /mcp endpoint is intentionally free of authentication and permanently read-only. The separate /mcp/actions endpoint requires Authorization: Bearer <username>:<disposableKey>, validates the key with MediaSFU, filters tools by key scope, and confirms side effects. See server/README.md.

Backend boundary

Use shared::backend.integration.guide for /v1/rooms, event settings, and disposable-key contracts. Never send credentials to the public/stdio tools. The action endpoint accepts only a disposable credential in the exact documented Authorization header and never exposes it to tools or logs.

Release gate

npm run release:check validates:

1. all 11 manifests and critical tools;
2. SDK registry drift and unregistered SDK discovery;
3. matching stdio and HTTP public tool surfaces;
4. all public and internal adapter coverage;
5. input, side-effect, path, redaction, timeout, and HTTP security controls;
6. production architecture, readiness, lifecycle, credential, and evidence behavior;
7. real isolated scaffold writes for all 11 SDK/runtime surfaces, including collision refusal and cleanup.

Run npm run pack:dry-run and npm audit before publication. Publishing is intentionally a separate maintainer action.

Additional public setup and deployment notes are in LOCAL_MCP_SETUP.md and server/README.md.

Project links

• Website and developer documentation: mediasfu.com
• Source: github.com/MediaSFU/mcp-sdk-tools
• Issues: github.com/MediaSFU/mcp-sdk-tools/issues
• Security reports: SECURITY.md

MediaSFU MCP SDK Tools is released under the MIT License.