MCP Interface

WebStream ships an MCP (Model Context Protocol) server, webstream-ops-mcp, that lets an AI assistant such as Claude, Cursor, or ChatGPT observe and administer your deployment through natural language — listing sessions, auditing access, onboarding users, publishing applications, and more. It exposes 89 tools, every one governed by an API key, a privacy mode, and a scope allowlist.

How it works

The MCP server is a small Node.js process that runs on the operator's machine (or a jump host). The AI client spawns it as a child process and talks to it over stdio — nothing listens on a network port. Every tool call is translated into an HTTPS request to the Gateway's /mcp/* proxy, authenticated with the X-MCP-Key header:

AI client (Claude / Cursor / ChatGPT)
    ↓ stdio (spawned child process)
webstream-ops-mcp  (privacy + scope filtering)
    ↓ HTTPS with X-MCP-Key header
Gateway  /mcp/*  proxy
    ↓                       ↓
/mcp/iam/*                /mcp/api/*
Access Management (IAM)   Metrics Engine

The Gateway validates the key against <mcpApiKeys> in app.config.xml before forwarding: /mcp/iam/* is served by the in-process IAM handlers, /mcp/api/* is proxied to the Metrics Engine. See Gateway for the proxy routing table.

Step 1 — Configure a gateway API key

Generate a key and add it to the <mcpApiKeys> section of app.config.xml on the gateway host, then restart the gateway. The name attribute is used for audit logging; the value is the secret the MCP server sends.

<mcpApiKeys>
  <key name="ops-admin" value="sk-mcp-0f3a...your-generated-key" />
</mcpApiKeys>

A quick way to generate a strong key:

python -c "import secrets; print('sk-mcp-' + secrets.token_hex(20))"

Step 2 — Build and configure the MCP server

The server lives in the webstream-ops-mcp folder of the WebStream distribution and requires Node.js 18 or later.

cd webstream-ops-mcp
npm install
copy config.example.json config.json   # cp on macOS/Linux

Edit config.json and set three values:

{
  "webstreamUrl": "https://your-gateway-host",
  "apiKey": "sk-mcp-0f3a...your-generated-key",
  "defaultOrgId": "default"
}

Build and verify:

npm run build
npm start

The server logs to stderr on startup. A healthy start looks like:

[webstream-ops-mcp v1.1.0] Starting MCP server...
[webstream-ops-mcp] Privacy mode: maskRestriction
[webstream-ops-mcp] Scope allow: [*]
[webstream-ops-mcp] Registered 89 tool(s), skipped 0 (out of scope)
[webstream-ops-mcp] Server running on stdio transport

Press Ctrl+C to stop — the AI client will spawn it automatically from here on.

Step 3 — Connect an AI client

Example: Claude Desktop

Claude Desktop reads its MCP server list from a JSON config file. Edit (or create) the file for your platform:

Add (or merge into) the mcpServers block, pointing at your built dist/index.js with an absolute path:

{
  "mcpServers": {
    "webstream-ops": {
      "command": "node",
      "args": ["C:/WebStream/webstream-ops-mcp/dist/index.js"]
    }
  }
}

Then:

1. Fully quit and restart Claude Desktop (File > Exit — closing the window is not enough).
2. Open the tools menu (hammer icon) in a new conversation — webstream-ops should be listed with its tools.
3. Verify end to end with a first prompt: “Show me all active streaming sessions”. Claude calls observe_active_sessions and the gateway logs the request against your key name.

Other clients

• Cursor — add the same mcpServers block to .cursor/mcp.json in your workspace root; Cursor detects it automatically.
• ChatGPT Desktop — Settings > Tools & Integrations > Add Server; command node, argument the absolute path to dist/index.js.

Security controls

Privacy modes

The privacyMode setting controls what per-user data the AI model ever sees. The same prompt produces different output in each mode:

Scope allowlist

The scope.allow list controls which tools are registered at startup. Tools outside the scope are not denied — they are invisible: the agent cannot discover or call them. Patterns are * (everything), category.* (a whole category), or category.tool (one tool).

Tool catalogue

The 89 tools are grouped into categories; the qualified tool name is category_tool (for example observe_active_sessions).

Sample prompts

Troubleshooting