# 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](https://docs.kloudfuse.com/platform/4.1.0/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-prerequisites)
- [1\. Enable the connector in custom_values.yaml](https://docs.kloudfuse.com/platform/4.1.0/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-values)
- [2\. (Optional) Customize the redirect URI allowlist](https://docs.kloudfuse.com/platform/4.1.0/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-redirect-uris)
- [3\. Apply the changes](https://docs.kloudfuse.com/platform/4.1.0/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-upgrade)
- [Verify](https://docs.kloudfuse.com/platform/4.1.0/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-verify)

## 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).

## Enable the connector in `custom_values.yaml`

Pick one of two install layouts:

- Standard Kloudfuse install (default)
- Separate kf-mcp helm release

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

```yaml
kf-mcp:
  enabled: true
```

Recommended for most installs.

Useful when you want to run a different kf-mcp version, image tag, or config than the standard install ships, or iterate on kf-mcp without re-running Kloudfuse upgrades. The kf-mcp Pod is installed by its own `helm install`; everything else (`/mcp` route, OAuth endpoints, auth) stays in the Kloudfuse install.

In `custom_values.yaml`:

```yaml
kf-mcp:
  enabled: false
```

After step 3 (`helm upgrade kfuse …​`) completes, install the kf-mcp chart separately into the same namespace as the Kloudfuse install:

```bash
helm install kf-mcp oci://us-east1-docker.pkg.dev/mvp-demo-301906/kfuse-helm/kf-mcp \
  --version <VERSION> \
  --namespace kfuse \
  -f kf-mcp-overrides.yaml
```

Replace `<VERSION>` with the kf-mcp chart version you want to install. kf-mcp is versioned independently from the Kloudfuse umbrella chart — pick the version your release notes (or Kloudfuse contact) call out as compatible with your install, or pin to a newer kf-mcp release if you want features ahead of the bundled sub-chart.

If the cluster has node taints (e.g. kfRoles-enabled production, owner-tainted dev), the override file needs matching `affinity` + `tolerations`. Replace `<KEY>` and `<VALUE>` with the node label/taint your cluster uses — the same pair appears in both blocks (e.g. `kf_role` / `query` for the standard Kloudfuse query pool):

```yaml
enabled: true

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: <KEY>                     # e.g. kf_role
              operator: In
              values:
                - <VALUE>                    # e.g. query
tolerations:
  - key: "<KEY>"                             # same key as above
    operator: "Equal"
    value: "<VALUE>"                         # same value as above
    effect: "NoSchedule"
```

For untainted clusters, `enabled: true` alone is sufficient.

|     |     |
| --- | --- |
|  | Install in the same namespace as the Kloudfuse install. Cross-namespace or cross-cluster setups are not supported by this layout. The kf-mcp chart sets `fullnameOverride: "kf-mcp"`, so the resulting Service is always named `kf-mcp`. |

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\. (Optional) Customize the redirect URI allowlist

Each AI client registers itself dynamically via RFC 7591 (DCR) on first use, then asks the authorization server to redirect the browser back to a client-specific callback URL after SSO. `user-mgmt-service` rejects any `redirect_uri` that is not on its allowlist.

The chart ships with a default that covers the supported clients out of the box — Claude Desktop / web, Codex (app + CLI), and Gemini CLI:

```yaml
user-mgmt-service:
  config:
    MCPConnector:
      AllowedRedirectURIs:
        - "http://localhost:*"                             # Codex / Gemini CLI (loopback)
        - "http://127.0.0.1:*"                             # Same, IPv4 literal
        - "https://claude.ai/api/mcp/auth_callback"        # Claude Desktop / Claude web
        - "https://claude.com/api/mcp/auth_callback"       # Same, .com TLD
```

You only need to override this list if you want a stricter allowlist (drop the loopback entries to lock out CLI clients, for example) or if you onboard a new MCP client whose callback URL is not in the default. Wildcard ports (`*`) on the loopback entries are required because the CLI clients bind a random ephemeral port for the OAuth callback.

To override, paste the same block into your `custom_values.yaml` with the entries you want — Helm replaces the list rather than merging.

If a user reports `invalid_redirect_uri` after a successful SSO sign-in, see [Troubleshooting → invalid_redirect_uri after sign-in](https://docs.kloudfuse.com/platform/4.1.0/ai-ml/mcp-server/oauth/troubleshooting/#invalid-redirect-uri).

## 3\. Apply the changes

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

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

For cluster-specific chart paths, version flags, and pre-flight steps, see [Upgrade Kloudfuse](https://docs.kloudfuse.com/platform/4.1.0/setup/upgrade/overview/).

## Verify

From any machine that can reach your cluster URL:

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

You should see a JSON document like:

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

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.