feat(kiali): add meshCluster parameter for multi-cluster support

[hhovsepy]

Summary

Adds multi-cluster support to the Kiali toolset for kiali/kiali#9895.

• meshCluster on eight Kiali tools — optional Istio mesh cluster name (e.g. west). Remapped internally to Kiali's clusterName API parameter via remapMeshCluster().
• kiali_list_mesh_clusters — discovery tool returning mesh cluster name and isHome.
• ClusterAware: false on all Kiali tools — the MCP server does not inject context on Kiali tools; mesh scope is selected only via meshCluster. Core Kubernetes tools still use context when multi-cluster is enabled.
• Multicluster mcpchecker evals — 6 tasks under evals/tasks/kiali/multicluster/ (mesh status, list clusters, remote metrics/workloads/topology/traces), plus setup-kiali-multicluster / run-evals-multicluster Makefile targets and CI job when suite=kiali.

Tools with meshCluster: get_mesh_traffic_graph, get_metrics, get_logs, get_pod_performance, list_or_get_resources, list_traces, manage_istio_config, manage_istio_config_read.

Why

Kiali exposes mesh cluster names (east, west, …), not kubeconfig context names. Auto-mapping MCP context → mesh cluster would fail silently in production and conflate two different concepts:

Parameter	Layer	Meaning
context	MCP provider (core tools only)	Which kubeconfig context / credentials
meshCluster	Kiali toolset	Which Istio mesh cluster Kiali should query

Models should call kiali_list_mesh_clusters when the target cluster is unknown, then pass the name value as meshCluster. Prompt guidance for the Kiali chatbot lives upstream in kiali/kiali#9981.

Test plan

• go test ./pkg/mcp/... (includes list_mesh_clusters integration test and TestKialiToolsNotClusterAware)
• Multicluster mcpchecker evals (6 tasks) + CI run-evaluation-multicluster for suite=kiali
• Manual: MCP server + Kiali in multi-cluster mode (east/west)
• Ask: metrics for productpage-v1 in bookinfo on cluster west → tool uses meshCluster=west
• Ask with ambiguous cluster → model calls kiali_list_mesh_clusters first

Related

• Issue: [AI] Enhance support for multi cluster kiali/kiali#9895
• Kiali MCP tools: [AI] Chatbot: Added support of Cluster Name in queries kiali/kiali#9927
• Kiali chatbot prompts: [AI] Guide multi-cluster tool usage via system prompts kiali/kiali#9981
• Multicluster evals (source): Add multi cluster evals hhovsepy/kubernetes-mcp-server#4

[Cali0707]

This seems very complex for models to figure out.

Is there a reason for this to be going through a secondary multi cluster level rather than implementing a cluster provider interface (like the one kcp did, or what is in pkg/kubernetes) ?

[hhovsepy]

The reason is that Kiali mesh clusters don't map to the Provider interface's model:

• GetDerivedKubernetes(ctx, target) assumes each target is a distinct
  Kubernetes API server with its own credentials. Kiali mesh clusters
  are not — a single Kiali instance (one URL, one bearer token) already
  sees all mesh clusters. GetDerivedKubernetes("east") and
  GetDerivedKubernetes("west") would return the same client.
• Only one provider can be active. A Kiali provider would replace the
  kubeconfig provider, losing multi-context support.
• Kiali handles multi-cluster routing internally via Istio's remote
  secrets. The MCP server just passes clusterName in the POST body
  as a query-scope parameter — same pattern as namespace on other tools.

I've simplified the docs to remove the dual-parameter explanation —
models only need to know about clusterName and kiali_list_clusters.
The context injection is already handled by the provider layer
transparently.

[Cali0707]

well the provider layer (while handling this transparently for toolsets) would expose this parameter to the models. My main concern is models getting confused over needing to set both a context and a clusterName for tool calls.

Maybe we can change the param to be a mesh cluster name or similar (just to clarify that this is for a mesh cluster, and not to select the actual target cluster).

E.g. if this is used with the ACM provider, this would lead to a model having both cluster and clusterName set as tool params, which would obviously be confusing

[hhovsepy]

Thank you for the clarification, I have renamed the clusterName param to 'meshCluster', will it be non confusing now?

[josunect]

I think the proposal of @Cali0707 makes sense, using a meshCluster parameter.

I understand the first proposal of creating a provider, so instead of clusterName being visible in the schema, the MCP would intercept the context parameter and translate it transparently to clusterName inside the Kiali handler before forwarding to Kiali.

The main issue is that the context name is not the Kiali cluster name, and it is not really a context change but a filter for Kiali, so probably it would need something extra in the configuration, like a cluster mapping.

For that reason, I think a meshCluster parameter would be more appropriate. Unlike context, which is a Kubernetes connection concept tied to kubeconfig (What Kiali should I use), meshCluster is explicitly scoped to the service mesh topology as Kiali understands it (What clusters from the mesh I want to check?), making the semantic boundary clear to both the model and the operator.

I will test this with Claude and see if there is any issue on the approach.

[manusa]

I discussed this internally with @josunect
I'm not sure if these changes are after our internal conversation or not.

Ideally, in order to keep things easy for models, it might be better we have a uniform way to access multi-cluster (this is what we have built in with the tool mutator)

I think the active thread with Calum is also about this.

I'm not sure if Josune did some research and findings.

[josunect]

@manusa I was doing some tests, when I ask from a specific cluster, Kiali returns the right data (using the MeshCluster arg). When asking for an specific context, it did a wrong call (With no previous knowledge), but next it made the right call. When asking for an specific context, it choose to use the kubernetes tool (When available).

Maybe we could use a new toolset config to be able to do a cluster mapping from context to cluster name and avoid this kind of issue.

MCP - Manual testing.txt

[josunect]

Another issue found, is that the MCP can pass the context to kiali, but, it is ignored, and Kiali returns the results from the home cluster (What happens in multi cluster when no cluster is passed). So, it can provide wrong results.

Maybe, if list clusters return the cluster name and the context, it could help.

[aljesusg]

Sorry, I was away last week; I agree with the proposed solution.

[github-actions]

👋 Heads up — this pull request changes files owned by @aljesusg @josunect.

You are listed as an owner of one or more of the changed areas in .github/CODEOWNERS. GitHub cannot auto-request review from owners without write access, so this comment is the notification instead. A review when you have a moment would be appreciated 🙏

[Cali0707]

@manusa I was doing some tests, when I ask from a specific cluster, Kiali returns the right data (using the MeshCluster arg). When asking for an specific context, it did a wrong call (With no previous knowledge), but next it made the right call. When asking for an specific context, it choose to use the kubernetes tool (When available).

Maybe we could use a new toolset config to be able to do a cluster mapping from context to cluster name and avoid this kind of issue.

@josunect I don't think this would work directly, this would be where you need a provider 🫠

The issue is that the provider is called to select a kube client before the toolset's tool is invoked, so we can't easily have the toolset change which cluster it is targetting...

A couple ideas that may work:

1. Do the provider approach, and name each target as "<cluster/context name>_". This would not exactly be trivial as we would need some way to figure out how to layer this provider on top of the existing multi cluster providers so that it could work with e.g. both ACM and kubeconfig multi cluster providers, so maybe isn't worth the complexity. But it would have the advantage of only having a single parameter, and no chance of model forgetting to set one/choosing wrong cluster for a kiali mesh
2. Add some kind of list_kiali_meshes tool that can present a map of target names to kiali mesh/cluster names. Again here we would need to figure out how to do some wiring changes as the whole idea until now has been that individual tools should be targetting a single cluster, so the tool params do not have access to more than one cluster. If we pursued this, we would probably want to introduce a concept of a multi cluster tool vs. a single cluster tool, which could be complicated...
3. Continue with this current approach, as the model seems to be able to recover well, and maybe add to the tool descriptions in this toolset to use the resources_list tool to see which kiali clusters are available on each target before calling anything

IMO option 3 seems like the easiest approach here. If that doesn't work as well as we like, my vote would be to try for option 1. I'd be happy to help with some of the work there, as I built out the providers originally

[josunect]

@manusa I was doing some tests, when I ask from a specific cluster, Kiali returns the right data (using the MeshCluster arg). When asking for an specific context, it did a wrong call (With no previous knowledge), but next it made the right call. When asking for an specific context, it choose to use the kubernetes tool (When available).
Maybe we could use a new toolset config to be able to do a cluster mapping from context to cluster name and avoid this kind of issue.

@josunect I don't think this would work directly, this would be where you need a provider 🫠

The issue is that the provider is called to select a kube client before the toolset's tool is invoked, so we can't easily have the toolset change which cluster it is targetting...

A couple ideas that may work:

1. Do the provider approach, and name each target as "<cluster/context name>_". This would not exactly be trivial as we would need some way to figure out how to layer this provider on top of the existing multi cluster providers so that it could work with e.g. both ACM and kubeconfig multi cluster providers, so maybe isn't worth the complexity. But it would have the advantage of only having a single parameter, and no chance of model forgetting to set one/choosing wrong cluster for a kiali mesh

2. Add some kind of `list_kiali_meshes` tool that can present a map of target names to kiali mesh/cluster names. Again here we would need to figure out how to do some wiring changes as the whole idea until now has been that individual tools should be targetting a single cluster, so the tool params do not have access to more than one cluster. If we pursued this, we would probably want to introduce a concept of a multi cluster tool vs. a single cluster tool, which could be complicated...

3. Continue with this current approach, as the model seems to be able to recover well, and maybe add to the tool descriptions in this toolset to use the resources_list tool to see which kiali clusters are available on each target before calling anything

IMO option 3 seems like the easiest approach here. If that doesn't work as well as we like, my vote would be to try for option 1. I'd be happy to help with some of the work there, as I built out the providers originally

@Cali0707 we were testing this approach (3) in the Kiali mcp itself, and worked fine. I think the risk here is that the mcp doesn't provide the cluster parameter to Kiali, in that case, Kiali will return the data from the home cluster. Maybe writing a provider for Kiali multi cluster that includes the cluster name from the kube config as the mesh cluster parameter?

[Cali0707]

@josunect maybe we can create some eval scenarios to capture this problem and see how prevalent it is?

[josunect]

@josunect maybe we can create some eval scenarios to capture this problem and see how prevalent it is?

Yes, we can create some evals for this. I guess we can create 2 jobs for the same workflow? And a new make target to setup a multi cluster environment.

[josunect]

@Cali0707 we have added some multi cluster evals. It looks like it is working as expected.

[Cali0707]

Thanks @josunect - one question (sorry for not thinking of this earlier): can you pull the multi cluster eval CI changes into a separate PR?

We've had lots of issues iteration there recently and I want to make sure we get this piece right, without blocking the rest of this PR