fix: filter kubernetes-only edges in MCP handler; add claude setup hints to kedge mcp url (#137)

* fix: filter kubernetes-only edges in MCP handler; add claude setup hints to mcp url

- mcp_builder.go: skip server-type edges when resolving MCP targets —
  server-type edges have no Kubernetes API, only SSH; including them
  in the MCP provider would fail or return empty toolsets
- mcp.go: after printing the MCP URL, print ready-to-use 'claude mcp add'
  command and Claude Desktop JSON snippet (includes bearer token from
  the active kubeconfig context when available)

Co-authored-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

* fix: rename MCP target parameter from 'edge' to 'cluster'

'edge' is kedge-internal terminology. Users think in terms of clusters.
Renaming the query parameter to 'cluster' makes the MCP target selection
more intuitive for the broader community.

Co-authored-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

* docs: document MCP integration in README, CONTRIBUTING, and DEVELOPERS

- README: add MCP to Features list, Quickstart section with example output,
  CLI reference entries for kedge mcp url
- CONTRIBUTING: add mcp packages to key packages table
- DEVELOPERS: add full MCP Integration section covering KubernetesMCP CRD,
  URL structure, request flow diagram, toolsets, target parameter, and
  per-edge MCP URL; update table of contents
- docs/developers.md: add MCP section for GitHub Pages site

Co-authored-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

* fix: update e2e tests to use 'cluster' parameter name for MCP tools/call

GetTargetParameterName() was renamed from 'edge' to 'cluster' but the
e2e test was still passing "edge": edgeName as the tools/call argument,
causing 'upstream unavailable' because the MCP server couldn't resolve
the target.

Co-authored-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

---------

Co-authored-by: mjudeikis-bot <ai@faros.sh>
Co-authored-by: Mangirdas Judeikis <mangirdas@judeikis.lt>

Author: 3 people

CONTRIBUTING.md

@@ -176,11 +176,13 @@ make test-e2e E2E_FLAGS=--keep-clusters
 | Package | Description |
 |---------|-------------|
 | `pkg/hub/controllers/edge/` | Edge lifecycle: token reconciler, RBAC, SSH credentials |
-| `pkg/virtual/builder/` | Agent-proxy virtual workspace — handles tunnel + status |
+| `pkg/hub/controllers/mcp/` | KubernetesMCP controller — sets status URL, tracks connected edges |
+| `pkg/virtual/builder/` | Agent-proxy + MCP virtual workspaces — handles tunnel, status, MCP handler |
 | `pkg/agent/` | Agent core: registration, tunnel, edge_reporter |
 | `pkg/agent/tunnel/` | revdial tunnel client (`StartProxyTunnel`) |
-| `pkg/cli/cmd/` | CLI command implementations |
+| `pkg/cli/cmd/` | CLI command implementations (including `kedge mcp url`) |
 | `apis/kedge/v1alpha1/` | Edge CRD types |
+| `apis/mcp/v1alpha1/` | KubernetesMCP CRD type (`mcp.kedge.faros.sh`) |
 
 ### Join token bootstrap flow
 

DEVELOPERS.md

@@ -9,6 +9,7 @@ Deep-dive reference for contributors working on kedge internals.
 - [Edge Proxy URL Format](#edge-proxy-url-format)
 - [SSH Server-Mode Internals](#ssh-server-mode-internals)
 - [kcp Workspace Hierarchy](#kcp-workspace-hierarchy)
+- [MCP Integration](#mcp-integration)
 - [Hub Controller Reference](#hub-controller-reference)
 
 ---
@@ -224,6 +225,120 @@ https://kedge.localhost:8443/clusters/<workspace-id>/...
 
 ---
 
+## MCP Integration
+
+kedge exposes all connected Kubernetes clusters as a single [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. AI agents (Claude, Cursor, Copilot, etc.) connect to this endpoint and can interact with all registered clusters using natural language.
+
+### KubernetesMCP CRD
+
+**API group:** `mcp.kedge.faros.sh/v1alpha1`  
+**Kind:** `KubernetesMCP`
+
+The `KubernetesMCP` object is automatically created as `default` in every tenant workspace by the hub bootstrapper. It acts as the configuration object for the multi-cluster MCP endpoint.
+
+```yaml
+apiVersion: mcp.kedge.faros.sh/v1alpha1
+kind: KubernetesMCP
+metadata:
+  name: default
+spec:
+  edgeSelector: {}   # empty = all kubernetes-type edges; use label selectors to restrict
+  readOnly: false    # set true to disable write operations (create/delete/apply)
+status:
+  URL: "https://hub.example.com/services/mcp/root:kedge:user-<id>/apis/mcp.kedge.faros.sh/v1alpha1/kubernetesmcps/default/mcp"
+  connectedEdges:
+  - my-cluster
+  - home-lab
+```
+
+### MCP URL structure
+
+```
+https://<hub>/services/mcp/<workspace-cluster-id>/apis/mcp.kedge.faros.sh/v1alpha1/kubernetesmcps/<name>/mcp
+```
+
+- `<workspace-cluster-id>` — kcp logical cluster name for the tenant workspace (from the server URL in the user's kubeconfig)
+- `<name>` — name of the `KubernetesMCP` object (usually `default`)
+
+### Request flow
+
+```
+AI agent (Claude / Cursor / …)
+    │  POST /services/mcp/<cluster>/…/default/mcp
+    │  Authorization: Bearer <user-token>
+    ▼
+hub MCP virtual workspace handler (pkg/virtual/builder/mcp_builder.go)
+    │
+    │  1. Extract bearer token, validate against kcp
+    │  2. Resolve workspace cluster from URL path
+    │  3. Fetch KubernetesMCP object for edgeSelector
+    │  4. List all edges in the workspace
+    │  5. Filter: kubernetes-type only + connected (tunnel active) + label selector
+    │  6. Build MultiEdgeKedgeEdgeProvider (one per request)
+    │
+    ▼
+kubernetes-mcp-server (github.com/containers/kubernetes-mcp-server)
+    │  MCP Streamable-HTTP protocol (tools/list, tools/call)
+    │
+    ▼
+KedgeEdgeProvider / MultiEdgeKedgeEdgeProvider (pkg/virtual/builder/mcp_provider.go)
+    │  GetTargets() → list of connected cluster names
+    │  GetDerivedKubernetes(cluster) → rest.Config via revdial tunnel
+    │
+    ▼
+Agent tunnel → target cluster kube-apiserver
+```
+
+### Target parameter
+
+When an MCP client wants to target a specific cluster, it passes `?cluster=<edge-name>` as a query parameter. The parameter name is `cluster` (not `edge`) because users think in terms of clusters.
+
+### Toolsets
+
+The MCP server registers toolsets from `kubernetes-mcp-server` via blank imports in `mcp_builder.go`:
+
+```go
+_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/config"
+_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/core"
+_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/helm"
+_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/kcp"
+_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/kiali"
+_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/kubevirt"
+```
+
+Each toolset registers its tools via `init()`. Without the blank imports, `tools/list` returns empty.
+
+### Adding to Claude Code
+
+```bash
+kedge mcp url --name default
+# prints URL + ready-to-use claude mcp add command with your token
+```
+
+Or manually:
+
+```bash
+claude mcp add --transport http kedge \
+  "https://hub.example.com/services/mcp/<cluster-id>/apis/mcp.kedge.faros.sh/v1alpha1/kubernetesmcps/default/mcp" \
+  -H "Authorization: Bearer <token-from-kubeconfig>"
+```
+
+### Per-edge MCP (single cluster)
+
+Each edge also exposes a direct MCP endpoint (independent of `KubernetesMCP`):
+
+```
+https://<hub>/services/agent-proxy/<workspace-cluster-id>/apis/kedge.faros.sh/v1alpha1/edges/<name>/mcp
+```
+
+```bash
+kedge mcp url --edge my-cluster
+```
+
+This bypasses `KubernetesMCP` and connects directly to a single edge's Kubernetes API.
+
+---
+
 ## Hub Controller Reference
 
 | Controller | Package | Responsibility |

README.md

@@ -7,6 +7,7 @@ kedge connects your distributed Kubernetes clusters and servers through a single
 - **Reverse tunnel connectivity** — agents dial out; no inbound firewall rules needed
 - **Kubernetes edge support** — proxy `kubectl` to any registered cluster via the hub
 - **SSH server mode** — manage non-Kubernetes hosts (VMs, bare metal) through the same hub
+- **MCP integration** — expose all connected clusters as a single [Model Context Protocol](https://modelcontextprotocol.io) server for AI agents (Claude, Cursor, etc.)
 - **OIDC authentication** — plug in any OIDC provider (Dex, Auth0, Okta, …)
 - **Static token auth** — quick setup for home labs and dev environments
 - **Multi-tenant workspaces** — per-user/team kcp workspace isolation
@@ -95,7 +96,36 @@ kedge kubeconfig edge my-cluster > kc.yaml    # get a kubeconfig for the edge
 kubectl --kubeconfig kc.yaml get nodes
 ```
 
-### 3. Connect a server (SSH mode)
+### 3. Use MCP with AI agents (Claude, Cursor, …)
+
+kedge exposes all your connected Kubernetes clusters as a single MCP server, letting AI coding assistants interact with your clusters directly.
+
+```bash
+# Print the MCP endpoint URL + ready-to-use setup commands
+kedge mcp url --name default
+```
+
+Example output:
+```
+https://hub.example.com/services/mcp/root:kedge:user-default/apis/mcp.kedge.faros.sh/v1alpha1/kubernetesmcps/default/mcp
+
+To add this MCP server to Claude Code:
+  claude mcp add --transport http kedge "https://hub.example.com/..." -H "Authorization: Bearer <token>"
+
+To add to Claude Desktop (claude_desktop_config.json):
+  {
+    "mcpServers": {
+      "kedge": {
+        "url": "https://hub.example.com/...",
+        "headers": { "Authorization": "Bearer <token>" }
+      }
+    }
+  }
+```
+
+The MCP server aggregates **all connected kubernetes-type clusters** into one endpoint. AI agents can list pods, describe deployments, apply manifests, and more — across all your clusters at once.
+
+### 4. Connect a server (SSH mode)
 
 ```bash
 kedge edge create my-server --type server
@@ -124,6 +154,8 @@ kedge ssh my-server -- df -h     # single command
 | `kedge ssh <name> -- <cmd>` | Run a single command on a server-mode edge |
 | `kedge agent run` | Start the agent as a foreground process |
 | `kedge agent join` | Install the agent as a persistent service (systemd / Deployment) |
+| `kedge mcp url --name <name>` | Print the KubernetesMCP multi-cluster MCP endpoint URL |
+| `kedge mcp url --edge <name>` | Print the per-edge MCP endpoint URL |
 
 ## Documentation
 

docs/developers.md

@@ -305,3 +305,36 @@ kedge dev create --chart-path deploy/charts/kedge-hub
 ```
 
 The agent establishes a reverse WebSocket tunnel to the hub, allowing the hub to proxy API requests to the agent's cluster.
+
+---
+
+## MCP Integration
+
+kedge exposes all connected Kubernetes clusters as a single [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server.
+
+### URL format
+
+```
+https://<hub>/services/mcp/<workspace-cluster-id>/apis/mcp.kedge.faros.sh/v1alpha1/kubernetesmcps/<name>/mcp
+```
+
+### Getting the URL
+
+```bash
+kedge mcp url --name default
+```
+
+This prints the URL and a ready-to-use `claude mcp add` command with your bearer token.
+
+### KubernetesMCP resource
+
+A `default` `KubernetesMCP` object is auto-created in every tenant workspace. It selects which kubernetes-type edges are included via `spec.edgeSelector` (empty = all connected kubernetes edges).
+
+### How it works
+
+1. The hub's MCP virtual workspace handler validates the bearer token.
+2. Lists all `Edge` objects in the workspace, filters to `spec.type: kubernetes` + connected + label selector.
+3. Builds a `MultiEdgeKedgeEdgeProvider` that dials each edge over its revdial tunnel.
+4. Passes control to `kubernetes-mcp-server` which implements the MCP protocol.
+
+See [DEVELOPERS.md](https://github.com/faroshq/kedge/blob/main/DEVELOPERS.md#mcp-integration) for the full internals reference.

pkg/cli/cmd/mcp.go

@@ -124,6 +124,36 @@ func runMCPURL(_ *cobra.Command, edgeName, kubernetesName string) error {
 	}
 
 	fmt.Println(mcpURL)
+
+	// Resolve the bearer token from the kubeconfig for the usage hint.
+	token := ""
+	if currentCtx, ok := rawCfg.Contexts[rawCfg.CurrentContext]; ok {
+		if u, ok := rawCfg.AuthInfos[currentCtx.AuthInfo]; ok {
+			token = u.Token
+		}
+	}
+
+	fmt.Println()
+	fmt.Println("To add this MCP server to Claude Code:")
+	if token != "" {
+		fmt.Printf("  claude mcp add --transport http kedge \"%s\" -H \"Authorization: Bearer %s\"\n", mcpURL, token)
+	} else {
+		fmt.Printf("  claude mcp add --transport http kedge \"%s\" -H \"Authorization: Bearer <your-token>\"\n", mcpURL)
+	}
+	fmt.Println()
+	fmt.Println("To add to Claude Desktop (claude_desktop_config.json):")
+	fmt.Println("  {")
+	fmt.Println("    \"mcpServers\": {")
+	fmt.Println("      \"kedge\": {")
+	fmt.Printf("        \"url\": \"%s\",\n", mcpURL)
+	if token != "" {
+		fmt.Printf("        \"headers\": { \"Authorization\": \"Bearer %s\" }\n", token)
+	} else {
+		fmt.Println("        \"headers\": { \"Authorization\": \"Bearer <your-token>\" }")
+	}
+	fmt.Println("      }")
+	fmt.Println("    }")
+	fmt.Println("  }")
 	return nil
 }
 

pkg/virtual/builder/mcp_builder.go

@@ -32,6 +32,7 @@ import (
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/kiali"
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/kubevirt"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 	"k8s.io/apimachinery/pkg/labels"
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"k8s.io/client-go/dynamic"
@@ -199,6 +200,14 @@ func (p *virtualWorkspaces) buildKubernetesMCPHandler() http.Handler {
 		for _, edgeObj := range edgeList.Items {
 			edgeName := edgeObj.GetName()
 			edgeLabels := edgeObj.GetLabels()
+
+			// Only include kubernetes-type edges — server-type edges provide
+			// SSH access only and have no Kubernetes API to proxy via MCP.
+			edgeType, _, _ := unstructured.NestedString(edgeObj.Object, "spec", "type")
+			if edgeType != "kubernetes" {
+				continue
+			}
+
 			if !edgeSelector.Matches(labels.Set(edgeLabels)) {
 				continue
 			}

pkg/virtual/builder/mcp_provider.go

@@ -103,8 +103,10 @@ func (p *KedgeEdgeProvider) GetDerivedKubernetes(_ context.Context, edgeName str
 // GetDefaultTarget returns an empty string — there is no single default edge.
 func (p *KedgeEdgeProvider) GetDefaultTarget() string { return "" }
 
-// GetTargetParameterName returns "edge" as the MCP target query parameter.
-func (p *KedgeEdgeProvider) GetTargetParameterName() string { return "edge" }
+// GetTargetParameterName returns "cluster" as the MCP target query parameter.
+// "cluster" is used rather than "edge" because users think in terms of clusters,
+// not kedge-internal "edge" terminology.
+func (p *KedgeEdgeProvider) GetTargetParameterName() string { return "cluster" }
 
 // WatchTargets is a no-op for v1; dynamic target reloading is not implemented.
 func (p *KedgeEdgeProvider) WatchTargets(_ mcpkubernetes.McpReload) {}
@@ -160,8 +162,8 @@ func (p *MultiEdgeKedgeEdgeProvider) GetDerivedKubernetes(ctx context.Context, e
 // GetDefaultTarget returns an empty string (no single default edge).
 func (p *MultiEdgeKedgeEdgeProvider) GetDefaultTarget() string { return "" }
 
-// GetTargetParameterName returns "edge".
-func (p *MultiEdgeKedgeEdgeProvider) GetTargetParameterName() string { return "edge" }
+// GetTargetParameterName returns "cluster".
+func (p *MultiEdgeKedgeEdgeProvider) GetTargetParameterName() string { return "cluster" }
 
 // WatchTargets is a no-op.
 func (p *MultiEdgeKedgeEdgeProvider) WatchTargets(_ mcpkubernetes.McpReload) {}

pkg/virtual/builder/mcp_provider_test.go

@@ -156,10 +156,10 @@ func TestGetDefaultTarget(t *testing.T) {
 	}
 }
 
-// TestGetTargetParameterName asserts that GetTargetParameterName returns "edge".
+// TestGetTargetParameterName asserts that GetTargetParameterName returns "cluster".
 func TestGetTargetParameterName(t *testing.T) {
 	provider := &KedgeEdgeProvider{}
-	if got := provider.GetTargetParameterName(); got != "edge" {
-		t.Errorf("GetTargetParameterName() = %q; want %q", got, "edge")
+	if got := provider.GetTargetParameterName(); got != "cluster" {
+		t.Errorf("GetTargetParameterName() = %q; want %q", got, "cluster")
 	}
 }

test/e2e/cases/mcp.go

@@ -254,7 +254,7 @@ func MCPEndpoint() features.Feature {
 			}
 
 			result, err := mcp.toolsCall(ctx, "namespaces_list", map[string]any{
-				"edge": edgeName,
+				"cluster": edgeName,
 			})
 			if err != nil {
 				t.Fatalf("tools/call namespaces_list failed: %v", err)
@@ -274,7 +274,7 @@ func MCPEndpoint() features.Feature {
 
 			result, err := mcp.toolsCall(ctx, "pods_list_in_namespace", map[string]any{
 				"namespace": "kube-system",
-				"edge":      edgeName,
+				"cluster":   edgeName,
 			})
 			if err != nil {
 				t.Fatalf("tools/call pods_list_in_namespace failed: %v", err)