Claude Code :: Kloudfuse Docs

Claude Code

Connect Claude Code (the CLI) to the Kloudfuse MCP server. Register the server with one CLI command, then complete SSO sign-in from inside Claude Code via /mcp. Tokens are stored locally and refreshed in the background — no service account token in your config.

In This Topic

Prerequisite

Claude Code installed (claude on your $PATH).
An operator has already enabled the connector on your Kloudfuse cluster by following Enable on the Cluster. If they haven’t, the Authenticate step below fails with a start_error or 401 from /mcp.

Install the Connector

Claude Code does this in two steps: register the server with the CLI, then authenticate from inside the running Claude Code session.

Register the server

Pick a friendly name for the server (the example uses kfuse; for multi-cluster setups, use a hostname-derived name like kfuse-prod):

claude mcp add --transport http --scope user kfuse https://<KLOUDFUSE_URL>/mcp

Replace <KLOUDFUSE_URL> with your cluster URL. The entry lands in ~/.claude.json under user scope and shows up in /mcp immediately.


	Don’t pass an `Authorization` header for OAuth clusters — the OAuth flow handles auth. Bearer-token clusters that don’t run the OAuth connector still need `--header "Authorization: Bearer <token>"` (see Install MCP Server in Kloudfuse).

Authenticate

Inside a running Claude Code session:

/mcp

Select the new server (kfuse in the example) from the menu.
Choose Authenticate — a browser tab opens at your Kloudfuse SSO sign-in page.
Sign in with your corporate identity (Okta, Azure AD, Google, SAML).
The token is stored automatically; refreshes happen in the background.


	Claude Code requires the explicit `Authenticate` step on first connect. Codex auto-triggers SSO on the first tool call, but Claude Code does not — if you skip authentication, the server stays in `not authenticated` status and tools won’t be callable.

Verify

After authenticating, run /mcp again. The server entry should now show:

kfuse
  Status:  ✔ connected
  Auth:    ✔ authenticated
  URL:     https://<KLOUDFUSE_URL>/mcp

Smoke-test a tool call from chat:

use kfuse to call prometheus_search_label_values with label_name "__name__" and start_time "now-5m"

A list of metric names confirms the connection is wired end-to-end.

Manage the Connector In-App

Claude Code exposes management both from the CLI and from inside the running session.

From the CLI

Replace <name> with the identifier you chose when adding the server (for example kfuse):

claude mcp list — show every configured MCP server, its scope, and connection status.
claude mcp get <name> — print the stored config for this entry.
claude mcp remove <name> — delete the server entry. Note: this does not clear stored OAuth tokens; remove them via /mcp → entry → Disconnect, or by reauthenticating.

From `/mcp` (inside Claude Code)

Open /mcp and select the server entry. The menu offers:

Authenticate / Reconnect — re-run the SSO flow. Use this after switching identities or if a token expires and Claude returns 401s.
Disable — temporarily skip this server without removing it from ~/.claude.json.

Multi-cluster

Re-run the claude mcp add command with a different name and URL. All entries coexist; pick one in /mcp per Claude Code session, or let Claude infer the right cluster from chat context.

claude mcp add --transport http --scope user kfuse-prod    https://kfuse-prod.example.com/mcp
claude mcp add --transport http --scope user kfuse-staging https://kfuse-staging.example.com/mcp

Alternative: Kloudfuse Plugin

If you’d prefer a guided setup that wraps the steps above into a single command, install the Kloudfuse Claude Code Plugin (kloudfuse/claude-plugin on GitHub) and run /kloudfuse:setup. The plugin auto-detects whether the cluster has OAuth enabled, derives a non-colliding server name, and runs claude mcp add for you.

/plugin marketplace add kloudfuse/claude-plugin
/plugin install kloudfuse@kloudfuse
/kloudfuse:setup

The end result is the same ~/.claude.json entry. Use whichever path fits — the plugin is the lower-friction option for single-cluster setups; the raw CLI is faster for scripted multi-cluster registration.