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 currently deployed pilot has no host shell or Kubernetes access. It does not replace existing break-glass or remote management tools.
Status
Current live pilot: whoami (read) and note_write (scratch-only write)
are authenticated through ChatGPT's OAuth connection. The optional
k8s_overview tool in this PR is source-only until the companion
yesvus/ops RBAC/network/token projection and a reviewed image digest are
explicitly deployed. It summarizes Node readiness, per-namespace Pod counts,
and unavailable Deployments without revealing raw Pod specifications, Secrets,
logs, service-account tokens or allowing host shell / Kubernetes writes.
The exec tier remains disabled.
Related MCP server: Dvarapala
Product boundary
Kule is a secure, self-hosted MCP server for infrastructure operations and privileged access, not a universal MCP gateway. Its scope is infrastructure and workspace operations, scoped credential workflows, host access, and its own authorization, sessions, audit and break-glass controls. The administration UI manages Kule only.
Prefer independently deployed, maintained upstream MCP servers for other domains (Grafana, Anki, GitHub). Preserve the OpenHands adapter as a compatibility bridge until native standalone MCP parity is verified. Do not aggregate unrelated tools or build a fleet control plane here. Fleet deployment and observability belong to the existing GitOps and Grafana stack.
See architecture issue #18 and ops #1178. This is the target boundary, not a claim about live rollout status.
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 considering them fully accepted.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.
Roles and targets. Opt-in integrations declare capabilities governed by the Developer, Operator or Break-glass roles, plus exact target allowlists. Role is derived only from authenticated groups/claims, never from a model or profile name. Every tool argument must be declared as an exact target or an explicit non-target input. Integration tools are denied if the registry is missing, disabled, any declared target is absent, or an argument is outside the policy. See docs/ws-oh-auth.md. This is source-only and default-off.
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 limit waiting, not arbitrary work. Worker-thread calls may outlive cancellation. Kubernetes status reads use cancellable async HTTP requests with an overall deadline; future host tools need their own process-level timeouts and termination.
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"
workspace_group = "mcp-workspace"
developer_group = "mcp-developers"
breakglass_group = "mcp-breakglass"
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
workspace_enabled = false # default-off; needs pinned Tezgah Pod identity
developer_enabled = false # default-off; non-operator workspace path
developer_isolation_verified = false # hard gate for the general Developer role
breakglass_enabled = false # default-off; needs a bounded expiry claim
breakglass_max_ttl_seconds = 900 # 60 to 3600
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 owner-approved OAuth/MCP gateway is live at
https://mcp.yesvus.com/mcp. Real ChatGPT DCR/OAuth and both pilot tools
have been verified. Kubernetes access is a separate reviewed rollout.
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.
The currently deployed pilot contains no developer-agent credentials, Docker socket, host paths, kubeconfig, service-account token or host tools. An optional read-only Kubernetes observer would require a dedicated, short-lived projected ServiceAccount identity in a separate rollout; its token must never appear in tool output or audit logs.
Optional Kubernetes read-only overview (NOT LIVE until separate GitOps rollout)
k8s_overview is registered only when the operator explicitly supplies
KULE_K8S_API_URL (for example,
https://kubernetes-api.internal:6443). The public OAuth server cannot choose an
arbitrary Kubernetes API path or HTTP method. The fixed internal API requests
list Nodes, Pods and Deployments; results are projected to aggregate status
fields only and refuse a paginated or oversized list rather than silently
claiming a partial healthy cluster.
To run safely, GitOps must mount a short-lived, projected Kubernetes
ServiceAccount token and the cluster CA at /var/run/kule-k8s/token and
/var/run/kule-k8s/ca.crt. The ServiceAccount must retain
automountServiceAccountToken: false. Its dedicated ClusterRole grants
only list for core nodes / pods and apps deployments.
No get secrets, pods/log, pods/exec, mutating verbs or
cluster-admin. NetworkPolicy allows exactly
the explicitly configured control-plane private endpoint on TCP 6443;
the cluster CA validates the Kubernetes API certificate. Private IP,
network-test outcomes and runtime admission evidence belong in the ops
workstream, rather than this public code README.
Enabling this source alone does not restart the running MCP Pod, update
its publicly available tools, change RBAC, or authorize a rollout.
The independent GitOps PR must pass exact-head review, RBAC
kubectl auth can-i negatives and the live disposable token read
before replacing the existing digest. SentinelX remains available for
break-glass until the Kule operator functionality is independently tested.
Optional OpenHands Agent Canvas management (source-only, off by default)
KULE_OPENHANDS_ENABLED=1 mounts a reviewed subset of the OpenHands Agent Canvas
management API imported from the pinned 1.62.0 OpenAPI schema. It requires a fixed
HTTPS origin, a dedicated X-Session-API-Key, and an exact approved
repository-to-path mapping. Session launch, rename, status, events, messaging,
interrupt/pause and per-conversation ACP model switch are allowlisted and require an
explicit repository scope backed by the native kulerepo tag; list continuations use
an encrypted gateway cursor instead of Canvas's global page ID. Conversation responses
are projected to lifecycle fields, and unapproved caller headers are stripped. Bash,
files, secrets, settings, profile mutation, plugins and the separate Automation
Service are not exposed. See docs/openhands.md for the complete
tool list, leg 2 interface and live-rollout gates. No live Canvas call or cluster
change is included.
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
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to call backend tools under per-agent policy, deciding which tools each agent can see, what arguments it may pass, how often it may call, and which writes wait for human approval. It also redacts secrets and PII from tool results, fences untrusted output against injection, and records every call in a hash-chained audit log.MIT