Enable on the Cluster

One-time cluster setup an operator runs to enable the OAuth custom connector. After this, end users connect Claude Desktop, Codex, or the Gemini CLI using the client-specific pages — no more operator involvement.

In This Topic

Prerequisites

  • A running Kloudfuse cluster with an upstream SSO identity provider already wired into kfuse-auth (Okta, Azure AD, Google, or SAML).

  • Cluster access to run helm upgrade.

  • Your cluster URL is reachable over HTTPS from each end user’s machine (the AI client opens the login page in the user’s browser).

1. Enable the connector in custom_values.yaml

Pick one of two install layouts:

The Kloudfuse install deploys the kf-mcp Pod alongside everything else. One helm release, one set of values.

kf-mcp:
  enabled: true
yaml

Recommended for most installs.

Either way, sessions survive helm upgrade; to force a re-auth across all users, delete the kfuse-mcp-oauth-dcr-secret and kfuse-mcp-oauth-signing-key Secrets and re-run helm upgrade.

2. Set the connector base URL

The connector advertises its OAuth endpoints (the .well-known discovery documents, /authorize, /token, and /register) at a single public base URL. AI clients read that base URL during login, so it must be the https:// hostname the user’s browser can actually reach.

By default Kloudfuse derives the base URL automatically as https://<tls.host>;, using the tls.host value already in your custom_values.yaml. If tls.host is set to the hostname your users reach the cluster on, you do not need to configure anything else — skip to the next step.

If tls.host is not set in your custom_values.yaml, the derived base URL is empty and the connector advertises an invalid issuer — OAuth login then fails for every client. In that case you must set the base URL explicitly:

user-mgmt-service:
  config:
    MCPConnector:
      BaseURL: https://<MCP_CONNECTOR_HOST>
yaml

Replace <MCP_CONNECTOR_HOST> with the full hostname end users reach (for example kloudfuse.example.com). The same override is also required for split-hostname deployments, where the connector is served on a different host than the one in tls.host.

An explicit MCPConnector.BaseURL always takes precedence over the tls.host-derived value. Whichever value applies, that host must serve the OAuth routes (/.well-known/…​, /authorize, /token, /register, and /mcp) — confirm with the Verify step below.

3. Apply the changes

Run the standard Kloudfuse upgrade command with your usual chart reference and custom_values.yaml. A representative form:

helm upgrade kfuse oci://us-east1-docker.pkg.dev/mvp-demo-301906/kfuse-helm/kfuse -f custom_values.yaml
bash

For cluster-specific chart paths, version flags, and pre-flight steps, see Upgrade Kloudfuse.

After the upgrade, wait for the kf-mcp Pod to reach Running, then restart user-mgmt-service so its Pod starts after kf-mcp. user-mgmt-service reads MCP connector state at startup and must come up second; if the user-mgmt-service Pod is older than the kf-mcp Pod, OAuth requests fail with a 401 until you restart it.

# Wait for kf-mcp
kubectl wait --for=condition=Ready pod -l app.kubernetes.io/name=kf-mcp -n <namespace> --timeout=180s

# Restart user-mgmt-service
kubectl rollout restart deploy/user-mgmt-service -n <namespace>

# Confirm ordering: user-mgmt-service AGE should now be lower than kf-mcp
kubectl get pods -n <namespace> -l 'app.kubernetes.io/name in (kf-mcp,user-mgmt-service)'
bash

Verify

From any machine that can reach your cluster URL:

curl https://<KLOUDFUSE_URL>/.well-known/oauth-protected-resource/mcp
bash

You should see a JSON document like:

{
  "resource": "https://<KLOUDFUSE_URL>/mcp",
  "authorization_servers": ["https://<KLOUDFUSE_URL>"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Kloudfuse MCP (OAuth)"
}
json

If this returns a 404 or an HTML page, the connector is not enabled yet — recheck the custom_values.yaml entries above.

Works on both Envoy Gateway and ingress-nginx clusters; no ingress-controller tweaks required.