Provides tools for exploring and operating Kubernetes/OpenShift clusters, including listing projects and resources, reading pods and logs, and (in higher modes) scaling workloads, restarting deployments, applying manifests, and deleting resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-openshift list pods in the openshift-console namespace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A safe-by-default Model Context Protocol server for OpenShift / Kubernetes. It lets an agent explore and operate a cluster — projects, pods and logs, deployments and deploymentconfigs, routes, services, builds, imagestreams, and any resource by kind — and, in higher modes, scale workloads, restart deployments, apply manifests, and delete.
Connect with a token from the web console you already use, or your username/password against the cluster's local identity provider.
Part of the dockndevai MCP server suite — one governance model across all of them.
Starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.
Tool | For | Needs mode |
| confirm the authenticated identity | read-only |
| projects/namespaces you can see | read-only |
| list any kind (± namespace, label selector) | read-only |
| one resource with full spec/status | read-only |
| a pod's container logs | read-only |
| recent events in a namespace | read-only |
| set replicas on a Deployment/DeploymentConfig | read-write |
| restart a Deployment | read-write |
| create/update from a manifest (SSA) | read-write + |
| delete a resource | admin + |
Related MCP server: Kubernetes MCP Server
npx -y @dockndevai/mcp-openshiftYou need your cluster's API URL and a credential. The quickest, since you use the browser console:
In the OpenShift web console, click your username (top-right) → Copy login command → Display Token. Copy the value after
--token=(sha256~…) and the URL after--server=.
Then set OPENSHIFT_SERVER + OPENSHIFT_TOKEN. (Console tokens are short-lived; grab a fresh one when it expires, or use username/password below, which re-logs in automatically.)
{
"mcpServers": {
"openshift": {
"command": "npx",
"args": ["-y", "@dockndevai/mcp-openshift"],
"env": {
"OPENSHIFT_SERVER": "https://api.cluster.example.com:6443",
"OPENSHIFT_TOKEN": "sha256~...",
"OPENSHIFT_MODE": "read-only"
}
}
}
}See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf, and .env.example for every variable.
Auth mode is chosen automatically (override with OPENSHIFT_AUTH):
token — OPENSHIFT_TOKEN (bearer). From the console (above) or oc whoami -t.
password — OPENSHIFT_USERNAME + OPENSHIFT_PASSWORD against the cluster's built-in OAuth server (HTPasswd / LDAP / any challenge-capable local IdP). The server runs the same request-token flow oc login -u … -p … uses, caches the token at ~/.mcp-openshift/token.json (0600), and re-logs in on expiry. The password is sent only to your cluster's OAuth endpoint and is never logged or written to disk.
TLS: clusters usually use a private CA — set OPENSHIFT_CA_CERT to the CA bundle, or (dev only) OPENSHIFT_INSECURE_TLS=true to skip verification.
Enforced by src/security.ts — defence in depth on top of your account's cluster RBAC:
OPENSHIFT_MODE — read-only (default) → read-write → admin. Tools above the mode aren't registered.
OPENSHIFT_NAMESPACE_ALLOWLIST / OPENSHIFT_PROTECTED_NAMESPACES — confine writes to named namespaces; system namespaces (kube-*, openshift, openshift-*, default) are readable but never mutable.
OPENSHIFT_ALLOW_APPLY — creating/updating resources needs this flag on top of read-write, plus a human confirmation.
OPENSHIFT_ALLOW_DELETE — deletes need admin mode plus this flag, plus confirmation.
OPENSHIFT_DRY_RUN — sends writes with Kubernetes dryRun=All: validated and admission-checked, but nothing persists.
Human-in-the-loop — apply, delete, and scale-to-zero pause and ask a person to approve via MCP elicitation.
OPENSHIFT_AUDIT_LOG — a JSON audit line per guarded op on stderr; Secret values are redacted from all output.
There is a bundled skill, openshift-safe-operations, that teaches an agent how to authenticate (including from the browser console), the safety rules, and the standard triage/operate workflows. See also SECURITY.md.
npm install
npm run build
# list the tools without a live cluster:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | OPENSHIFT_SERVER=https://x:6443 OPENSHIFT_TOKEN=x node dist/index.js
npm testMIT
Fetch a single resource by kind + name (+ namespace for namespaced kinds), with its full spec/status. Secret values are redacted.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Resource kind — e.g. pod, deployment, deploymentconfig, service, route, configmap, secret, build, buildconfig, imagestream, statefulset, daemonset, job, cronjob, pvc, node, project. Singular or plural accepted. | |
| name | Yes | Resource name | |
| namespace | No | Namespace / project. Required for namespaced kinds; omit for cluster-scoped. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds two genuinely useful behavioral traits beyond those hints: secret values are redacted, and the response includes full spec/status, which an agent needs to set expectations. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core operation is front-loaded, and the important caveat about secret redaction is included without added noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-resource read with 100% schema coverage and read-only annotations, the description covers identity, namespace eligibility, and return content. It does not specify error behavior such as not-found handling, but that is a minor gap and no output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by clarifying the namespace rule—required for namespaced kinds, omitted for cluster-scoped—and by framing kind+name as the identity key, going beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Fetch'), resource ('single resource'), and key identifiers (kind, name, namespace), and names the return content (spec/status). This clearly distinguishes it from sibling list_resources, which fetches a collection rather than one item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates the canonical use case—fetching one resource by identity—and gives explicit namespace guidance: required for namespaced kinds, omitted for cluster-scoped. It does not explicitly name alternatives or exclusion conditions, but the single-resource framing strongly implies when to use it over list_resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent events in a namespace — the fastest way to see why something is failing to schedule/start.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max events (capped by OPENSHIFT_MAX_RESULTS) | |
| namespace | Yes | Namespace / project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about recency and diagnostic purpose, but does not disclose ordering, pagination, or event-level behavior. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler: it opens with the action and resource, then immediately supplies the practical value. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only list tool with fully documented parameters and strong annotations, the description is sufficient for correct invocation. It does not specify output formatting or event ordering, but the return shape is reasonably inferable from the tool's name and purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the namespace and limit parameters are already fully documented. The description reinforces the namespace scope and recency but does not need to repeat parameter details, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List recent events in a namespace,' and adds a clear diagnostic rationale. This distinguishes it from sibling tools like list_resources and get_resource by focusing on events and scheduling/start failures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when you need to see why something is failing to schedule or start. It does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the projects (namespaces) you can see, with name, display name and phase. Start here to find a namespace to work in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful scoping: 'projects you can see' indicates visibility filtering, and it enumerates the fields returned. No additional behavioral caveats are needed for this simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short clauses front-load the core action and return fields, followed by a single-purpose usage hint. Every sentence earns its place; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with strong annotations, the description covers what it returns, who can see it, and how to use it. No output schema exists, so the explicit field list compensates for that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description cannot add parameter-level detail. Per the baseline for 0-param tools, a 4 is appropriate; the description does explain the output fields, which is the relevant semantic content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' with the resource 'projects (namespaces)' and specifies the returned fields (name, display name, phase). It distinguishes this from sibling list_resources by clarifying these are namespaces, and its 'Start here' note positions it as the entry point for namespace discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the tool's context: 'Start here to find a namespace to work in,' which tells the agent when to use it. It does not explicitly name alternatives or exclusions, but the context is clear enough for a read-only list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List resources of a kind, optionally in a namespace and filtered by a label selector. Returns the raw Kubernetes/OpenShift list (secret values are redacted). Works for core and OpenShift kinds (pods, deployments, deploymentconfigs, routes, services, builds, imagestreams, …).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Resource kind — e.g. pod, deployment, deploymentconfig, service, route, configmap, secret, build, buildconfig, imagestream, statefulset, daemonset, job, cronjob, pvc, node, project. Singular or plural accepted. | |
| limit | No | Max items (capped by OPENSHIFT_MAX_RESULTS) | |
| namespace | No | Namespace / project. Required for namespaced kinds; omit for cluster-scoped. | |
| label_selector | No | Label selector, e.g. app=web,tier!=cache |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those: it returns the raw Kubernetes/OpenShift list, redacts secret values, and supports both core and OpenShift kinds. It does not over-claim or contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, each earning its place: the first gives the core action and filters, the second states the return shape and redaction behavior, and the third lists supported kinds with examples. The most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate 4-parameter tool with no output schema, the description covers the return shape, redaction, and scope of supported kinds. It is not exhaustive about error cases or authentication, but the schema and annotations fill the remaining gaps, so only the lack of explicit sibling routing keeps this from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents kind, limit, namespace, and label_selector with examples and constraints. The description adds only general context about kinds and raw output, which is not parameter-specific, so it meets the baseline without materially extending schema meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List resources of a kind') with optional namespace and label-selector scoping. It clearly distinguishes itself from siblings like get_resource (single resource) and list_projects (specific kind) by covering any core/OpenShift kind and returning a raw list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when you need a list of resources of a kind, optionally scoped by namespace or label selector. However, it does not explicitly contrast with get_resource, pod_logs, list_events, or list_projects, so an agent must infer the selection criteria from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a pod's container logs (most recent lines). Optionally a specific container or the previous instance.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name (from list_resources kind=pod) | |
| previous | No | Read the previous (crashed) container instance's logs | |
| container | No | Container name (defaults to the first / only container) | |
| namespace | Yes | Namespace / project the pod is in | |
| tail_lines | No | How many trailing lines to return (default 200) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description adds context like 'most recent lines' and 'previous instance', which clarify what is returned. It does not disclose output format or whether pagination applies, but for a read-only tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the core purpose immediately and omits any redundant phrasing. Every clause adds useful scope information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only log tool with a complete schema and robust annotations, the description and structured fields cover required parameters, defaults, and behavior. The lack of an output schema is not critical here since log output is inherently textual, but no return format is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all five parameters, including defaults and limits. The description's mention of 'a specific container or the previous instance' merely echoes parameter meanings without adding new detail, meriting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Read') and resource ('a pod's container logs'), and adds optional scope (container, previous instance). It does not explicitly distinguish itself from sibling tools like get_resource or list_events, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to choose this tool over siblings or when not to use it. There is no mention of prerequisites (e.g., getting a pod name via list_resources) or any exclusions, leaving usage entirely implied by the verb 'Read'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the authenticated user (name and groups) — confirm which identity the server is using.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the useful detail that the result includes name and groups, but it does not go beyond that into edge cases like unauthenticated responses, which would have added further transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tight sentence with no filler. The core action, output content, and purpose are all front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only identity check with comprehensive annotations, the description covers everything an agent needs: what it does, what it returns, and why to call it. There is no missing information that would hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is essentially complete. The description implies no input is needed, which matches the empty schema; the baseline of 4 applies because there is nothing for parameter documentation to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Return') and resource ('authenticated user') plus the precise content ('name and groups'). It clearly differentiates from all sibling tools, which operate on projects, resources, logs, or events rather than the caller's identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the tool's use case: confirm which identity the server is using. It does not explicitly list exclusions or alternatives, but the sibling tools are sufficiently different that the intended context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_resourcelist_eventslist_projectslist_resourcespod_logswhoamiScored across 6 tools
The six tools each target a distinct concern: identity, project discovery, generic resource listing, single-resource retrieval, logs, and events. The only mild overlap is list_projects vs list_resources with kind='projects', but the specialized project listing is clearly differentiated by its friendlier return format and explicit 'start here' intent.
Most tools follow a verb_noun pattern (list_projects, list_resources, get_resource, list_events), but whoami and pod_logs break that pattern, one being a bare command and the other a noun_noun compound. The names are still readable, but the conventions are mixed.
Six tools is well-scoped for a read-only OpenShift inspection server. Each tool earns its place and together they form a compact workflow without unnecessary bloat.
The set covers the main diagnostic lifecycle: confirm identity, discover projects, list and fetch resources, read pod logs, and inspect events. It lacks mutating operations like create/update/delete, but the described surface appears intentionally read-only, so the gaps are minor for that purpose.
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
