mcp

command
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README

MCP Virtual Workspace

Serves the Model Context Protocol as a kcp virtual workspace, scoped to what the calling user can actually see.

An agent connected to a kcp installation needs two things: a list of workspaces it may work on, and a way to act in them as the human who asked. This component provides the second. The first comes from the access virtual workspace in this repository, which answers SelfClusterAccessReview.

See kcp-dev/kcp#3839.

How it works

Registered as a raw-handler virtual workspace at /services/mcp. Raw rather than a delegated apiserver because MCP is JSON-RPC over streamable HTTP — there is no group, version or resource for the fixed-group-version machinery to serve. It still sits behind the root apiserver's filter chain, so authentication, authorization and audit are the framework's rather than hand-rolled.

Two things happen per request: the caller's workspace list is fetched from the access virtual workspace and cached briefly, and per-workspace API calls are made with this server's own credential impersonating the caller. Both deserve explanation.

Layout

Path Description
cmd cobra commands: serve, init, operator.
config/apiexport the marketplace offering: the mcp APIExport, its MCPEndpoint schema, the client instructions ConfigMap, the bind grant.
pkg/bootstrap init: applies config/apiexport into root:mcp:controllers and mints the server's identity.
pkg/operator watches the export's endpoint slice; writes the impersonation grant and the MCPEndpoint report into each workspace that enabled MCP.
internal/config flag surface.
internal/access client for the access virtual workspace, with the per-caller cache.
internal/mcp the virtual workspace: serving, authentication, per-caller scope.
pkg/tools the shared kit MCP tools, one package per toolset, each exposing Register.
pkg/toolsets maps toolset names to Register functions; owns validation and the default selection.
deploy/helm chart.
deploy/kcp front-proxy path mapping and the RBAC this server's identity needs.
test/e2e deploys the real thing into kind and speaks MCP to it.

Running

make build

bin/mcp-virtual-workspace serve \
  --kubeconfig=$KUBECONFIG \
  --access-url=https://localhost:9443/services/access \
  --secure-port=9444 \
  --authentication-config=/path/to/kcp/authentication-config.yaml

Serving is TLS-only; a self-signed certificate is generated for development when none is supplied. At least one authentication method is required — the server refuses to start otherwise, because every caller would be anonymous and the symptom would be an empty tool list rather than an error.

The authentication configuration must match kcp's. Prefer --authentication-config pointing at the same AuthenticationConfiguration file kcp is started with; the --oidc-* flags work too but have to be kept in step by hand.

Connecting a client

Any MCP client that can send a bearer token works: the front-proxy validates it against the same issuer as every other kcp request and forwards the identity, and the server then acts as that person. In the Tilt stack the issuer is dex at https://dex.kcp.localhost:8443/dex, the server is https://kcp.localhost:8443/services/mcp, and the console's own OAuth client — kcp, public, PKCE — is the one to use.

Why dynamic client registration does not work here

The MCP spec expects a client to find its authorization server by itself: fetch RFC 9728 metadata from the resource, fetch the server's RFC 8414 metadata from the issuer, register a client there (RFC 7591), sign in. This server implements its half — --oauth-authorization-servers turns on the /.well-known/oauth-protected-resource endpoint and the WWW-Authenticate hint on every 401, served ahead of the authentication filters — but two things in front of and behind it stop the flow:

  • kcp's front-proxy authenticates everything. An unauthenticated request for the metadata never reaches this server; the proxy answers it with its own 401, a Kubernetes Status with no WWW-Authenticate. The client then falls back to treating the server's origin as the authorization server and POSTs /register to it — which is the Dynamic Client Registration rejected (HTTP 401): {"kind":"Status",…} Claude Code reports.
  • dex has no registration endpoint. Its metadata carries no registration_endpoint, so even a client that found it could not register.

Until that changes — the honest fix is this server on its own hostname, authenticating OIDC tokens directly so discovery is reachable, plus a registration endpoint that hands every registrant the public client — clients have to be given the client up front.

Claude Code

Pre-registered client, with discovery pointed straight at the issuer:

claude mcp add-json kcp '{"type":"http","url":"https://kcp.localhost:8443/services/mcp","oauth":{"clientId":"kcp","callbackPort":8000,"authServerMetadataUrl":"https://dex.kcp.localhost:8443/dex/.well-known/openid-configuration"}}'
claude mcp login kcp

No secret — kcp is a public client — and port 8000 is a redirect URI dex has for it (hack/tilt/dex.yaml). The plain claude mcp add form fails for the reasons above. Claude Code runs on Node, which does not share the browser's certificate exceptions, and the stack uses two self-signed CAs (kcp's and dex's), so start it from a shell with both in one bundle:

kubectl --kubeconfig .tilt/tilt-contrib.kubeconfig config view --raw \
  -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > /tmp/kcp-bundle.pem
cat .tilt/dex/ca.crt >> /tmp/kcp-bundle.pem
export NODE_EXTRA_CA_CERTS=/tmp/kcp-bundle.pem
Codex

Codex's OAuth flow needs registration too, so give it a token instead. contribctl login runs the browser flow against dex and caches the ID token, which kcp accepts as a bearer:

bin/contribctl login --issuer https://dex.kcp.localhost:8443/dex --url https://kcp.localhost:8443
export KCP_MCP_TOKEN=$(jq -r '.[].idToken' ~/.config/tenancyctl/tokens.json | head -1)
# ~/.codex/config.toml
[mcp_servers.kcp]
url = "https://kcp.localhost:8443/services/mcp"
bearer_token_env_var = "KCP_MCP_TOKEN"

Codex trusts the system store, so import both CA certificates there.

Checking without a client

The same thing by hand: a token from dex's password grant (development only; enablePasswordDB in the Tilt dex config) and an initialize through the front-proxy, the request the e2e tests also start from:

TOKEN=$(curl -sk -X POST https://dex.kcp.localhost:8443/dex/token \
  -d grant_type=password -d client_id=kcp -d scope='openid email groups' \
  -d username=alice@team-a.example.com -d password=password | jq -r .access_token)
curl -sk -X POST https://kcp.localhost:8443/services/mcp \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

A 200 with "serverInfo":{"name":"kcp"} means the whole chain — proxy, token, server — is fine, and anything a client still reports is on the client's side: usually the certificate, or registration.

The same instructions, in the console

Whoever enables MCP in a project sees these steps on the producer's page in the console, with the server, issuer, client id and their own workspace filled in. They come from config/apiexport/instructions.yaml, a ConfigMap the mcp APIExport names in its marketplace.kcp.hub/instructions annotation; init applies it with the export, and the marketplace mirrors it into the catalog. To change what people are told, edit that file and apply it into the controllers workspace — no rebuild:

kubectl --kubeconfig .tilt/tilt-contrib.kubeconfig \
  --server https://kcp.localhost:8443/clusters/root:mcp:controllers \
  apply -f mcp/config/apiexport/instructions.yaml

The format and the {{variables}} it may use are documented in the marketplace README.

Testing

make test is unit tests. make test-e2e is the real thing:

make test-e2e          # tears the cluster down afterwards
make test-e2e-keep     # keeps it for inspection (NO_TEARDOWN=true)

It needs kind, kubectl, helm, docker, go and git. The script creates a kind cluster, installs cert-manager and kcp-operator, builds this image from the working tree and the access virtual workspace from its main branch, and then deploys kcp, both virtual workspaces and two consumer workspaces.

It then asks list_kcp_workspaces over MCP twice, with two credentials that have opposite rights: a client certificate for alice, and a bearer token for agent from the front-proxy's static token file. Each must see its own workspace and not the other's — expectations that only both hold if the answer followed the caller.

That covers the parts no unit test can: kcp-operator rendering a Deployment this binary accepts, the front-proxy routing /services/mcp and turning either credential into the identity headers this server trusts, and the impersonated round trip to the access virtual workspace.

Not covered: callers that reach this server directly with a JWT, i.e. --authentication-config and the --oidc-* flags. In e2e the front-proxy is always the one validating credentials, and this server only ever authenticates X-Remote-* headers.

kcp-operator tracks a moving branch, so the job can go red without anything here having changed — which is the point. Pin it with KCP_OPERATOR_REF. The access virtual workspace is built from this repository at the same revision, so the two virtual workspaces can never drift apart. The script's header lists every knob.

One such red is outstanding: the access virtual workspace needs the revision where access-vw-init merges its assets instead of replacing them. Before it, init creates the APIExportEndpointSlice and can never re-apply it — kcp defaults spec.export.path and rejects the update as a changed reference — so any restart of that init container is a permanent crash loop and the access VW never becomes ready. Until that lands on its main branch, run with ACCESS_VW_SRC or ACCESS_VW_REF pointing at a revision that has it.

make verify renders the e2e manifests without a cluster, so a template typo fails in seconds rather than after kcp has been stood up.

Toolsets

Tools are grouped into toolsets, enabled with --toolsets (default: core). The selection is enforced server-side — a toolset that is not enabled is never registered, so no client, model or prompt can reach it. That makes the flag operator policy over what AI agents may do, not a client preference.

Toolset Default Tools
core yes list_kcp_workspaces, list/get_kcp_apibindings, list/get_kcp_apiexports, list_kcp_apiexportendpointslices, list/get_kcp_workspacetypes, list_kcp_initializingworkspaces, list_kcp_terminatingworkspaces, list_resources, get_resource
apis no list/get_kcp_apiresourceschemas, list_kcp_apiconversions
admin no list_kcp_logicalclusters, list_kcp_shards, list_kcp_partitions, list_kcp_partitionsets
write no create_resource, update_resource, patch_resource, delete_resource, scale_resource

core is everything an agent needs to navigate its workspaces and read any resource in them, including CRDs and bound APIs, via the generic list_resources/get_resource. apis is API producer machinery, admin is kcp operator internals (shards and topology exist only in the root workspace), and write is free-form mutation — all opt-in because they are noise or risk for ordinary callers. Every tool remains subject to the caller's scope and to kcp's authorization through impersonation regardless of toolset selection.

Status

Alpha. The tools live in pkg/tools/* subpackages, exported so other MCP servers can reuse them by implementing tools.Scope. Writes act as the caller through impersonation, so kcp's RBAC decides what is allowed.

FAQ

Why no local access graph. This component could run its own RBAC indexer, but that would double the watch load on kcp and produce two answers that can disagree. Asking the access virtual workspace instead keeps one source of truth, and makes SelfClusterAccessReview earn its keep as a real API rather than an internal function call. The cost is an HTTP hop, which the per-caller cache (--access-cache-ttl, default 30s) amortises across the many tool calls a single MCP session makes. The access graph is already eventually consistent, so the TTL widens an existing staleness window rather than introducing a new one.

Enabling MCP is a marketplace offering. MCP is not an API, so there is nothing for a consumer to bind in order to "get" it. What they actually have to do is let this server act as them in their workspace — see the impersonation note below — and that is a per-workspace, opt-in, revocable grant, which is exactly the shape of an enablement.

So config/apiexport/ publishes one APIExport whose permission claims cover the RBAC that grant needs. Binding it is the consent; mcp operator watching the export's endpoint slice spends those claims on the single impersonation ClusterRole and ClusterRoleBinding, and then writes an MCPEndpoint into the workspace so whoever enabled it can see that it worked and where to point a client. Deleting the binding revokes the claims and with them the operator's reach — consent and capability are the same fact, rather than two things that can drift.

MCPEndpoint has no spec on purpose: there is nothing to ask for, because the binding is the request. It is a report.

Why impersonation, not the caller's token. Behind kcp's front-proxy the caller's bearer token is consumed by the proxy, which forwards identity as X-Remote-* headers instead. There is no token left to replay, so this server acts through impersonation: kcp authorizes every per-workspace request as the caller, and the audit log records both identities. That requires impersonate on users and groups in the core group, and on userextras/* in authentication.k8s.io.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
config
apiexport
Package apiexport holds the kcp-side assets the mcp component needs in the workspace hosting its APIExport.
Package apiexport holds the kcp-side assets the mcp component needs in the workspace hosting its APIExport.
internal
access
Package access asks the access virtual workspace which workspaces a caller can see.
Package access asks the access virtual workspace which workspaces a caller can see.
mcp
Package mcp serves the Model Context Protocol as a kcp virtual workspace.
Package mcp serves the Model Context Protocol as a kcp virtual workspace.
pkg
bootstrap
Package bootstrap installs the mcp component's kcp-side objects: the workspace that owns them, the APIExport a consumer enables by binding, and the grant the operator needs to read through it.
Package bootstrap installs the mcp component's kcp-side objects: the workspace that owns them, the APIExport a consumer enables by binding, and the grant the operator needs to read through it.
operator
Package operator turns a consumer's APIBinding into working MCP.
Package operator turns a consumer's APIBinding into working MCP.
tools
Package tools is the shared kit for kcp MCP tools: the Scope authorization contract every tool operates within, plus helpers for GVR parsing and unstructured object handling.
Package tools is the shared kit for kcp MCP tools: the Scope authorization contract every tool operates within, plus helpers for GVR parsing and unstructured object handling.
tools/admin
Package admin provides read tools for kcp operator internals — LogicalClusters, Shards, Partitions and PartitionSets.
Package admin provides read tools for kcp operator internals — LogicalClusters, Shards, Partitions and PartitionSets.
tools/apis
Package apis provides read tools for the machinery of kcp's API sharing model — APIResourceSchemas and APIConversions.
Package apis provides read tools for the machinery of kcp's API sharing model — APIResourceSchemas and APIConversions.
tools/core
Package core is the default toolset: navigating the caller's workspaces (workspaces, APIBindings, APIExports, WorkspaceTypes, workspace lifecycle) plus generic read access to any resource by GVR.
Package core is the default toolset: navigating the caller's workspaces (workspaces, APIBindings, APIExports, WorkspaceTypes, workspace lifecycle) plus generic read access to any resource by GVR.
tools/write
Package write provides generic mutation tools — create, update, patch, delete and scale by GVR.
Package write provides generic mutation tools — create, update, patch, delete and scale by GVR.
toolsets
Package toolsets names the groups of MCP tools an operator can enable.
Package toolsets names the groups of MCP tools an operator can enable.
sdk
apis/mcp/v1alpha1
Package v1alpha1 holds the API type for the mcp component (group mcp.platform.kcp.io).
Package v1alpha1 holds the API type for the mcp component (group mcp.platform.kcp.io).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL