operator-mcp
The k3s dual-client pilot uses Authentik as the OIDC identity provider, with an Authentik MFA fresh-login gate that must pass before the endpoint is exposed to clients such as ChatGPT and Claude.ai.
Performs OAuth 2.1 with PKCE (S256) against an OpenID Connect provider, discovering endpoints from the configured oidc_config_url and using the token's groups claim to authorize tool access by group membership. Includes dynamic client registration with an allowlisted set of redirect URIs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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: needsrequired_group.operate: needsrequired_group.exec: needsrequired_groupandexec_group, andtools.exec_enabled = true. Anything not allowed is hidden from the tool list and denied at call time.
Kill switch. If the file
<state_dir>/DISABLEDexists, 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"withallow_pod_bind = trueonly 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_groupwho 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=valuesecrets 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 auditedRequired environment variables (never put these in the file):
Variable | Purpose |
| OIDC client secret |
| 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.tomlRunning 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/mcpPut 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Zero-trust gateway for AI agents: score tool calls, verify agent cards, enforce policy, audit.
Runtime permission, approval, and audit layer for AI agent tool execution.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceProvides permission gates and tamper-evident audit logging for AI agent tool executions, with declarative policies, consent ladders, and hash-chained verification.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables 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.3MIT