Skip to main content
Glama
operator-mcp

operator-mcp

by yesvus

operator-mcp

A small, self-hosted MCP server for a restricted operator pilot. It exposes tools to an AI client over Streamable HTTP, and every call is authenticated, authorized by group membership, and recorded in a tamper-evident audit log. The first release intentionally has no host shell or Kubernetes access. It does not replace existing break-glass or remote management tools.

Status

P1 spike. Not production. The only tools today are whoami (read) and note_write (writes a note into a scratch directory). They exist to prove the authentication, authorization and audit paths end to end. There are no shell or host-changing tools yet, and the exec tier is wired but unused.

Related MCP server: Dvarapala

Architecture

  • Authentication. FastMCP's OIDC proxy performs OAuth 2.1 with PKCE (S256) against your OpenID Connect provider. The server issues its own tokens, and dynamic client registration only accepts redirect URIs in allowed_client_redirect_uris. The default list covers ChatGPT and the documented exact Claude.ai manual OAuth-client callback; validate both client flows end to end before public exposure.

  • Authorization. The token's groups claim decides access. Each tool carries exactly one tier tag:

    • read: needs required_group.

    • operate: needs required_group.

    • exec: needs required_group and exec_group, and tools.exec_enabled = true. Anything not allowed is hidden from the tool list and denied at call time.

  • Kill switch. If the file <state_dir>/DISABLED exists, every tool call is refused. Remove the file to re-enable. The refusal is audited.

  • Audit log. Append-only JSONL. Each record stores the SHA-256 of the previous line. Verify with operator-mcp audit-verify <path>. Call arguments and error details are passed through best-effort secret redaction before they are written.

  • Network. The server binds to loopback by default. A Pod may opt into host = "0.0.0.0" with allow_pod_bind = true only behind a ClusterIP, restricted NetworkPolicy and approved TLS ingress; it does not expose host networking.

Security model: what this does NOT protect against

  • Exec-group callers are effectively the service user. Anyone in exec_group who can reach an exec tool has the service account's full power on the host. Keep that group tiny, and treat membership as root-equivalent.

  • OAuth is not a sandbox. Authentication says who is calling; it does not limit what a permitted tool can do once it runs.

  • Timeouts stop waiting, not work. A tool that blocks in a worker thread keeps running after its deadline; tools that run commands must enforce their own subprocess timeouts and kill the process.

  • Redaction is best-effort. Known token shapes and key=value secrets are masked. Unusual secret formats can still reach the audit log or tool output. Tools must not read secrets in the first place.

  • The newest audit record is unprotected. The chain only covers lines that have a successor, so truncating or editing the tail is not detectable from the file alone.

  • The audit chain detects tampering; it does not prevent it. A host administrator (root) can rewrite the whole file and recompute the chain. Ship the log off the host for stronger guarantees.

  • Compromise of the identity provider or the reverse proxy is outside this server's control. Protect those systems as you would the host.

Configuration

Non-secret settings live in TOML. Secrets come only from the environment.

# /etc/operator-mcp/config.toml
[server]
host = "127.0.0.1"                     # default; Pod may use 0.0.0.0
allow_pod_bind = false                  # true only for an isolated Pod listener
port = 8795
public_url = "https://mcp.example.com" # https only; the reverse proxy serves this
state_dir = "/var/lib/operator-mcp"    # DISABLED kill-switch file lives here

[auth]
oidc_config_url = "https://id.example.com/.well-known/openid-configuration"
client_id = "operator-mcp"
required_group = "mcp-operators"
exec_group = "mcp-exec"
groups_claim = "groups"
# allowed_client_redirect_uris = [...]  # defaults to ChatGPT + exact Claude callback

[audit]
path = "/var/log/operator-mcp/audit.jsonl"

[tools]
exec_enabled = false
scratch_dir = "/var/lib/operator-mcp/scratch"
timeout_seconds = 30       # 1 to 110
max_output_bytes = 65536  # 1024 to 1048576; larger results are refused and audited

Required environment variables (never put these in the file):

Variable

Purpose

OPERATOR_MCP_OIDC_CLIENT_SECRET

OIDC client secret

OPERATOR_MCP_JWT_SIGNING_KEY

Signing key for issued tokens, at least 32 characters

Check the configuration without starting the server:

operator-mcp check-config --config /etc/operator-mcp/config.toml

Running locally

Requires Python 3.11 or newer.

pip install .
export OPERATOR_MCP_OIDC_CLIENT_SECRET=...           # from your IdP
export OPERATOR_MCP_JWT_SIGNING_KEY="$(openssl rand -hex 32)"
operator-mcp serve --config ./config.toml            # listens on 127.0.0.1:8795/mcp

Put a reverse proxy in front of it that forwards https://mcp.example.com to 127.0.0.1:8795. Clients discover the OAuth endpoints from public_url.

Development

pip install -e '.[dev]'
pytest -q
ruff check .
ruff format --check .

The test suite includes an integration test of the HTTP auth path against a fake OIDC provider on loopback, so it needs no network access.

License

Apache License 2.0. See LICENSE.

k3s dual-client pilot (ops #461)

The deployment definitions and approval gates live in yesvus/ops under cluster/operator-mcp-pilot/. The client URL will be https://mcp.yesvus.com/mcp; do not expose this endpoint until the Authentik MFA fresh-login gate (#803), verified image digest and protected-route review pass.

  • ChatGPT: OAuth DCR with only the documented redirect URI patterns. Check the exact callback selected by the ChatGPT plugin builder; write-tool support must be proven on the actual account.

  • Claude.ai: prefer its published client identity when compatible; otherwise choose automatic registration, with an exact fallback callback https://claude.ai/api/mcp/auth_callback. Never permit a wildcard Claude domain.

  • The FastMCP OAuth storage backend must be explicitly verified on Linux. A data directory alone does not prove that DCR registrations survive process restarts. Reconnect/re-register and token lifecycle are acceptance tests.

  • Scratch notes, audit records and the kill switch use an isolated volume. Audits redact secrets best-effort; they must not be treated as durable external evidence until exported to the logging pipeline.

  • No developer-agent credentials, Docker socket, host paths, kubeconfig, service-account token or host-operation tools are part of this pilot.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides permission gates and tamper-evident audit logging for AI agent tool executions, with declarative policies, consent ladders, and hash-chained verification.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables secure exposure of internal tools to LLM clients with API-key authentication, tenant isolation, per-tool guardrails, PII scrubbing, rate limiting, audit logging, and telemetry over stdio and HTTP/SSE.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables developers to expose product operations as model-callable tools over stdio or Streamable HTTP with bearer-token auth, per-client rate limits, host allow-listing, structured call logging, and a swappable backend for secure, testable deployments.
      3
      MIT