Tool

Use / Avoid

Risk

Permissions and prerequisites

Parameters and constraints

Scope selection

Expected data shape

Common failures

Flow

Example

openshift_connection_info

Use to inspect MCP/OpenShift/Vault/Postgres wiring. Avoid for workload data.

read-only

Requires healthy service connections.

userId?

Uses resolved userId to show scope model paths.

server metadata, persistence health, connection info

503 backend unavailable

Start here before troubleshooting, then openshift_health_check.

{ "userId": "alice" }

openshift_health_check

Use for API reachability/liveness. Avoid for version/capability details.

read-only

Requires OpenShift endpoint access; token optional by auth mode.

userId?

User token is loaded from Vault for that user.

upstream health response

401/403 token or RBAC, 503 API down

After setting token, run before other OpenShift calls.

{ "userId": "alice" }

openshift_get_version

Use to read API server version. Avoid for upgrade planning details.

read-only

OpenShift API reachable.

userId?

Token by user scope.

Kubernetes/OpenShift version payload

403/503

After health check; pair with openshift_get_cluster_version.

{}

openshift_list_endpoints

Use to discover MCP-known convenience endpoints. Avoid for full dynamic API discovery.

read-only

None beyond server startup.

none

Not user-scoped.

{ endpoints: [...] }

rare; 500 internal only

Follow with openshift_api_request or dedicated tools.

{}

openshift_discover_api_groups

Use for full installed API group/version inventory. Avoid when dedicated tool already exists.

read-only

OpenShift discovery endpoints enabled.

userId?

Token by user scope affects visible groups.

groups/versions discovery

403, 503

Prerequisite for openshift_discover_api_resources.

{ "userId": "alice" }

openshift_discover_api_resources

Use to discover resources/verbs/subresources for one API version. Avoid guessing plural names.

read-only

Requires valid apiVersion from discovery.

apiVersion, userId?

Token by user scope.

resource list with verbs/subresources

404 apiVersion missing, 403

Run after openshift_discover_api_groups; before openshift_resource_request.

{ "apiVersion": "apps/v1" }

openshift_discover_openapi

Use for schema-level request/response structure. Avoid for live objects.

read-only

OpenAPI v3 available on cluster.

schemaPath?, userId?

Token by user scope.

OpenAPI index or one schema document

404 schemaPath invalid, 503

Use before crafting complex body payloads.

{ "schemaPath": "apis/apps/v1" }

openshift_list_projects

Use to enumerate accessible namespaces/projects. Avoid if exact project known.

read-only

User token should have project list/get rights.

userId?

Token by user scope.

project list

403

Use before namespace-scoped calls.

{ "userId": "alice" }

openshift_get_project

Use for one project details/status. Avoid for broad listings.

read-only

Project must exist and be visible by RBAC.

projectName, userId?

Token by user scope.

project object

404, 403

Follow openshift_list_projects.

{ "projectName": "my-project" }

openshift_list_pods

Use to list pods in namespace with selectors. Avoid for logs/details of one pod.

read-only

Namespace access required.

namespace, labelSelector?, fieldSelector?, userId?

Namespace + user token scope.

pod list

403, 404 namespace

Follow with openshift_get_pod / openshift_get_pod_logs.

{ "namespace": "my-project", "labelSelector": "app=api" }

openshift_get_pod

Use to inspect one pod state/containers. Avoid for historical log analysis.

read-only

Pod must exist and be readable.

namespace, podName, userId?

Namespace + user token scope.

pod object

404 pod, 403

Start after openshift_list_pods.

{ "namespace": "my-project", "podName": "api-abc123" }

openshift_get_pod_logs

Use for container logs with tail/time controls. Avoid for metrics/events.

read-only

Pod/log RBAC needed.

namespace, podName, container?, previous?, tailLines? (>=0), sinceSeconds? (>0), timestamps?, userId?

Namespace + user token scope.

log text or structured log response

400 invalid options, 404 pod/container

Use after identifying pod/container.

{ "namespace": "my-project", "podName": "api-abc123", "tailLines": 200 }

openshift_list_events

Use to troubleshoot warnings/failures by event stream. Avoid for object spec retrieval.

read-only

Event API and RBAC required.

namespace?, fieldSelector?, `type? (Normal

Warning), userId?`

Cluster or namespace by args + user scope.

event list

403

Pair with pod/deployment diagnostics.

openshift_list_deployments

Use to inspect deployments in namespace. Avoid for scaling/restart actions.

read-only

Apps API readable.

namespace, labelSelector?, fieldSelector?, userId?

Namespace + user token scope.

deployment list

403, 404

Pre-check before scale/restart.

{ "namespace": "my-project" }

openshift_list_services

Use to list service frontends. Avoid for route hostnames.

read-only

Core services API readable.

namespace, labelSelector?, userId?

Namespace + user token scope.

service list

403, 404

Pair with routes/pods for traffic debugging.

{ "namespace": "my-project" }

openshift_list_routes

Use to list OpenShift routes. Avoid on pure Kubernetes clusters without route API.

read-only

Route API installed and authorized.

namespace, labelSelector?, userId?

Namespace + user token scope.

route list

404 API absent, 403

Follow with openshift_get_route.

{ "namespace": "my-project" }

openshift_get_route

Use for one route host/TLS/backends. Avoid for list use-cases.

read-only

Route must exist and be readable.

namespace, routeName, userId?

Namespace + user token scope.

route object

404 route/API absent, 403

After listing routes.

{ "namespace": "my-project", "routeName": "frontend" }

openshift_list_cluster_operators

Use to assess operator health/degradation. Avoid for workload troubleshooting only.

read-only

OpenShift config APIs available.

userId?

Cluster scope, token by user.

ClusterOperator list/conditions

404 API absent, 403

Pair with cluster version and events.

{}

openshift_get_cluster_version

Use to inspect desired/current updates and history. Avoid for node-level issues.

read-only

ClusterVersion API available.

name?, userId?

Cluster scope, token by user.

ClusterVersion object

404 API/name, 403

Use with openshift_get_version.

{}

openshift_list_nodes

Use for node inventory/conditions. Avoid for per-pod details.

read-only

Node list RBAC required.

labelSelector?, fieldSelector?, userId?

Cluster scope, token by user.

node list

403

Pair with openshift_get_resource_usage for capacity checks.

{ "labelSelector": "node-role.kubernetes.io/worker" }

openshift_can_i

Use for RBAC preflight checks. Avoid as a substitute for full policy audit.

read-only

SubjectAccessReview permission path available.

verb, resource, apiGroup?, namespace?, resourceName?, userId?

User token scope.

authorization decision details

403 on SAR endpoint

Run before mutating operations to preflight rights.

{ "verb": "patch", "resource": "deployments", "namespace": "my-project" }

openshift_list_role_bindings

Use to inspect namespace/cluster RoleBindings. Avoid for full RBAC graphing.

read-only

RBAC APIs readable.

namespace?, labelSelector?, userId?

Cluster-wide or namespace scope.

RoleBinding list

403

Follow with openshift_can_i for action checks.

{ "namespace": "my-project" }

openshift_list_crds

Use to inventory installed CRDs. Avoid for CR instance data itself.

read-only

apiextensions API readable.

labelSelector?, userId?

Cluster scope, token by user.

CRD list

403, 404 API absent

Pair with discovery tools and openshift_resource_request.

{}

openshift_list_subscriptions

Use to inspect OLM subscriptions. Avoid if OLM not installed.

read-only

OLM APIs and RBAC required.

namespace?, labelSelector?, userId?

Cluster or namespace scope.

subscription list

404 OLM API absent, 403

Pair with operator troubleshooting flows.

{ "namespace": "openshift-operators" }

openshift_get_resource_usage

Use for live metrics (pods/nodes). Avoid as a long-term monitoring replacement.

read-only

Metrics API (metrics.k8s.io) must be installed.

`resourceType (pods

nodes), namespace?, name?, labelSelector?, userId?`

Scope depends on resource type and namespace.

usage metrics list/object

404 metrics API absent, 403

Prereq: validate metrics API via discovery.

openshift_get_user_token_metadata

Use to verify token metadata/index state without exposing token. Avoid for setting/revoking token.

read-only

Metadata key and Vault token path may or may not exist.

userId

Exact user scope required.

tokenConfigured flag, metadata record, index entry

404/503 backing store errors

Use after set/deactivate operations to verify state.

{ "userId": "alice" }

Tool

Use / Avoid

Risk

Permissions and prerequisites

Parameters and constraints

Scope selection

Expected data shape

Common failures

Flow

Example

openshift_scale_deployment

Use to change replica count. Avoid for rollout image/env changes.

mutating

Requires valid authorizationKey when admin auth configured and RBAC to patch scale.

namespace, deploymentName, replicas (int >= 0), userId?, authorizationKey?

Namespace + user token scope.

scale result/deployment summary

401 auth key, 403 RBAC, 404 deployment

Prereq: openshift_list_deployments; follow with openshift_get_pod/events.

{ "namespace": "my-project", "deploymentName": "api", "replicas": 3, "authorizationKey": "..." }

openshift_rollout_restart

Use for restart via pod-template annotation patch. Avoid for full rollout strategy changes.

mutating

Requires mutating auth and deployment patch rights.

namespace, deploymentName, restartedAt? (ISO datetime), userId?, authorizationKey?

Namespace + user token scope.

rollout restart patch result

401, 403, 404

Prereq: check deployment health; follow with events/pod status.

{ "namespace": "my-project", "deploymentName": "api", "authorizationKey": "..." }

openshift_resource_request

Use for any discovered resource operation by coordinates. Avoid when a dedicated tool exists for safer validation.

high-risk for mutating verbs

For POST/PUT/PATCH/DELETE, mutating auth required. Requires accurate discovery coordinates.

apiVersion, resource, method (GET/POST/PUT/PATCH/DELETE default GET), optional namespace, name, subresource, query?, body?, headers?, userId?, authorizationKey?

Uses user token; namespace optional based on resource scope.

passthrough API response

400 malformed coordinates/body, 401 mutating auth, 403 RBAC, 404 resource

Prereq: discovery tools; follow with targeted read tool.

{ "apiVersion": "apps/v1", "resource": "deployments", "namespace": "my-project", "method": "GET" }

openshift_api_request

Use for raw path/non-resource APIs not covered elsewhere. Avoid for common workflows where dedicated tools exist.

high-risk for mutating verbs

Mutating verbs require authorizationKey; path must be valid API path.

method, path, optional query?, body?, headers?, userId?, authorizationKey?

Path is normalized to leading /; token by user scope.

passthrough API response

400 invalid path/method, 401, 403, 404

Prereq: openshift_list_endpoints or discovery; follow with specific read validation.

{ "method": "GET", "path": "/apis/apps/v1/namespaces/my-project/deployments" }

openshift_set_user_token

Use to create/rotate a user's OpenShift bearer token and metadata/index records. Avoid for temporary session-only tokens.

high-risk

Mutating auth required when configured; Vault and Postgres must be writable.

userId, token, optional tokenId, expiresAt, scopes[], audience[], authorizationKey?

Writes to user-scoped Vault token path, shared token index, and user metadata key.

redacted token path/index metadata summary

401, 422 Vault write/read issues, 503 backends

Prereq: mcp_admin_auth_verify; follow with openshift_get_user_token_metadata and openshift_health_check.

{ "userId": "alice", "token": "sha256:replace-me", "authorizationKey": "..." }

openshift_deactivate_user_token

Use to revoke user token, mark index inactive, and delete user token secret. Avoid if you only need metadata inspection.

high-risk destructive

Mutating auth required when configured. Operation is destructive for direct token secret.

userId, authorizationKey?

Affects only selected user scope and shared index entry for that token hash.

{ userId, tokenSecretPath, tokenIndexPath, active:false }

401, 503 Vault/store failures

Prereq: confirm target with openshift_get_user_token_metadata; follow with metadata check and health check as that user.

{ "userId": "alice", "authorizationKey": "..." }

Tool

Use / Avoid

Risk

Permissions and prerequisites

Parameters and constraints

Scope selection

Expected data shape

Common failures

Flow

Example

mcp_admin_auth_status

Use to confirm whether mutating guard is active and where verifier is sourced. Avoid for key validation.

read-only

Vault reachable for final source of truth.

none

Global server scope.

{ configured, source, vaultPath, rotatedAt }

503 Vault unavailable

Prereq for verify/rotate runbooks.

{}

mcp_admin_auth_verify

Use to test an authorizationKey without mutation. Avoid as a substitute for role management.

read-only security check

Requires candidate key.

authorizationKey

Global auth verifier scope.

{ authorized: true } on success

401 invalid key, 503 vault issues

Run before all mutating calls.

{ "authorizationKey": "current-admin-key" }

mcp_admin_auth_rotate

Use to replace admin key hash in Vault. Avoid frequent unnecessary rotation in active automations without client coordination.

high-risk mutating

Requires currently valid authorizationKey; new key min length 16.

authorizationKey, newAuthorizationKey (min 16)

Global auth verifier scope.

{ configured:true, source:"vault", vaultPath, rotatedAt }

401 invalid current key, 409 not bootstrapped, 503 Vault

Prereq: status + verify; follow by updating all clients and re-verify.

{ "authorizationKey": "old-key", "newAuthorizationKey": "new-key-with-16-plus" }

Tool

Use / Avoid

Risk

Permissions and prerequisites

Parameters and constraints

Scope selection

Expected data shape

Common failures

Flow

Example

redshift_list_clusters

Use to list configured clusters for user without credentials. Avoid for connectivity validation.

read-only

Redshift feature enabled and config store readable.

userId?

User-scoped config prefix redshift.cluster.*.

metadata list with clusterId and updatedAt

503 config store

Prereq before selecting clusterId.

{ "userId": "alice" }

redshift_get_cluster

Use to inspect one cluster metadata. Avoid for secrets (never returned).

read-only

Cluster record must exist.

clusterId, userId? (clusterId normalized/lowercase policy)

User + cluster selection.

one metadata record

404 cluster missing, 400 invalid id

Follow redshift_list_clusters.

{ "clusterId": "analytics" }

redshift_health_check

Use to validate connection/auth to selected cluster. Avoid for SQL validation.

read-only

Cluster metadata and Vault credentials must exist.

clusterId, userId?

User + cluster selection.

connectivity/status fields

404 cluster, 422 missing credentials, network errors

Run before redshift_query.

{ "clusterId": "analytics", "userId": "alice" }

redshift_set_cluster

Use to create/replace cluster connection + credentials. Avoid storing ad-hoc temporary credentials.

high-risk mutating

Mutating auth required when configured; Vault and Postgres writable.

clusterId, host, database, username, password, optional port (1-65535 default 5439), ssl (default true), timeoutMs (>0 default 15000), userId?, authorizationKey?

Writes metadata to Postgres and credentials to Vault for user+cluster.

stored metadata (credentials excluded)

401, 400 invalid id/port, 503 stores

Prereq: verify admin key; follow with health check.

{ "clusterId": "analytics", "host": "example.redshift.amazonaws.com", "database": "warehouse", "username": "svc", "password": "secret", "authorizationKey": "..." }

redshift_remove_cluster

Use to delete metadata and credentials for one cluster. Avoid if you only want to disable query access temporarily.

high-risk destructive

Mutating auth required when configured.

clusterId, userId?, authorizationKey?

Removes selected user+cluster config and secret.

{ clusterId, deleted }

401, 400 invalid id, 503 store errors

Prereq: list/get to confirm target; follow by list check.

{ "clusterId": "analytics", "authorizationKey": "..." }

redshift_query

Use for parameterized SQL on a selected cluster. Avoid non-parameterized dynamic SQL from untrusted input.

high-risk mutating/data-impacting

Mutating auth required when configured; cluster and credentials must exist.

clusterId, sql, optional parameters[] (default []), maxRows (1-10000 default 1000), userId?, authorizationKey?

Executes in selected user+cluster context.

result rows/metadata limited by maxRows

401, 404 cluster, 422 missing creds, SQL/runtime errors

Prereq: health check; follow with read-back validation query.

{ "clusterId": "analytics", "sql": "select * from users where id = $1", "parameters": [42], "maxRows": 100 }

Tool

Use / Avoid

Risk

Permissions and prerequisites

Parameters and constraints

Scope selection

Expected data shape

Common failures

Flow

Example

config_get

Use to read user-scoped config keys. Avoid for secret material (use Vault-backed tools).

read-only

Postgres reachable.

key, userId?

Reads one key in selected user scope.

{ userId, key, value, updatedAt }

503 db errors

Prereq: know exact key naming.

{ "key": "redshift.cluster.analytics" }

config_set

Use to write user-scoped non-secret config JSON. Avoid storing credentials/tokens in config.

mutating

Mutating auth required when configured; Postgres writable.

key, value, userId?, authorizationKey?

Writes one key in selected user scope.

{ userId, key, value, updatedAt }

401, 503 db errors

Prereq: optional config_get; follow with config_get verification.

{ "key": "feature.flag.demo", "value": { "enabled": true }, "authorizationKey": "..." }