# 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/latest/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-prerequisites)

- [1. Enable the connector in custom_values.yaml](https://docs.kloudfuse.com/platform/latest/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-values)

- [2. Set the connector base URL](https://docs.kloudfuse.com/platform/latest/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-baseurl)

- [3. Apply the changes](https://docs.kloudfuse.com/platform/latest/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-upgrade)

- [Verify](https://docs.kloudfuse.com/platform/latest/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).

## 1. 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. 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:<br>```yaml<br>user-mgmt-service:<br>  config:<br>    MCPConnector:<br>      BaseURL: https://<MCP_CONNECTOR_HOST><br>```<br>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](https://docs.kloudfuse.com/platform/latest/ai-ml/mcp-server/oauth/enable-on-cluster/#oauth-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:

```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/latest/setup/upgrade/overview/).

|     |     |
| --- | --- |
|  | 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.<br>```bash<br># Wait for kf-mcp<br>kubectl wait --for=condition=Ready pod -l app.kubernetes.io/name=kf-mcp -n <namespace> --timeout=180s<br># Restart user-mgmt-service<br>kubectl rollout restart deploy/user-mgmt-service -n <namespace><br># Confirm ordering: user-mgmt-service AGE should now be lower than kf-mcp<br>kubectl get pods -n <namespace> -l 'app.kubernetes.io/name in (kf-mcp,user-mgmt-service)'<br>```<br>|

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