🤖 feat: activate the CoderMCPServer controller

[ThomasK33]

Summary

The CoderMCPServer controller now runs. A CoderMCPServer creates and manages one MCP server config in a Coder organization, which Coder chats offer to the model. Before this PR the kind was dormant: its controller was not registered and its CRD was not installed.

This is plan step M9 of #155. Steps M1 to M8 landed in earlier PRs, the last ones as #368 (delete path), #371 (E2E stub), #376 (test S9) and #377 (the opt-in /status admission policy).

What changes

1. internal/app/controllerapp/controllerapp.go registers CoderMCPServerReconciler.
2. The CRD moves from config/crd/dormant/ to config/crd/bases/, into config/default/kustomization.yaml and dist/install.yaml. hack/update-manifests.sh drops it from DORMANT_CRDS, and the CI dormancy guard step for the kind goes.
3. RBAC markers: get, list, watch, patch on codermcpservers, get and update on codermcpservers/status, update on codermcpservers/finalizers. The secrets rule does not change (test S9, 🤖 test: pin the Secret RBAC rules and the standalone API server RBAC #376, passes).
4. A sample with its credential Secret: config/samples/coder_v1alpha1_codermcpserver.yaml.
5. The how-to docs/how-to/manage-mcp-servers.md, plus the nav, the index, the architecture page, the controller deploy page and the getting-started cleanup.
6. The API reference page docs/reference/api/codermcpserver.md. The "no effect yet" sentences leave the spec.mcpServers field docs of CoderControlPlane and the CoderMCPServer types.
7. The E2E path filter gains internal/controller/codermcpserver*.

What the how-to documents

• The control plane opt-in (spec.mcpServers.organizations, allowForceOn): organization names resolve to IDs, and a withdrawn opt-in disables each affected server with one enabled: false update and no credential read. The object then reports DisabledExternally until a spec edit.
• The credential Secret contract (label, destinations annotation, value rules), and that Coder sends the credential again after a redirect.
• Access: spec.access lists groups only, so every sync removes user grants added in the dashboard. With access omitted, Coder's default lets the organization's Everyone group read the server.
• The 🤖 CoderMCPServer: decide whether an unresolved group blocks removing old access #313 fail-closed behavior on a missing group: remove unnamed entries, add nothing, send enabled: false if the generation disables the server, and add the groups once they exist.
• The CoderMCPServer: test the opt-in disable after a crash between marker write and PATCH, and document the window (before M9) #365 disable window and its known limit.
• Rotation, URL changes (and their order), dashboard kill switches, the credential kill switch, the emergency path, and deletion (from 🤖 feat: delete the Coder MCP server config of a deleted CoderMCPServer #368).
• The Coder-side limits (plan 5.5): access checked only at chat selection, tool lists by exact name, OAuth2 tokens deleted on a URL change, encryption at rest only with enterprise keys, no address guard.
• RBAC guidance: what each permission means in Coder, a viewer Role, an editor Role, the wildcard warning, a ResourceQuota note.
• config/admission/: opt-in (the install bundle does not apply it), needs ValidatingAdmissionPolicy (GA in Kubernetes 1.30), and hard-codes the ServiceAccount system:serviceaccount:coder-system:coder-k8s. Edit it when the operator runs as another ServiceAccount.

Dogfood

A full run of plan section 8 on a private Kind cluster (kind v0.26.0, kindest/node v1.32.0, Coder v2.37.2, no license), with images built from 091c7fcf. That commit has the same controller code as this head. Later commits changed only docs, the CI path filter, and moved the GitOps health rules out. Every step passed:

Step	Result
Opt-in, Secret, apply	Ready 233 ms after apply. Coder holds the slug, URL, enabled, has_api_key, and an ACL of Everyone read only. The key appears 0 times in the CR JSON and the operator logs.
Dashboard and chat	The server shows in AI settings > MCP servers. A chat that selects it gets the stub's answer. The stub got a matching key hash, and the LLM got e2e-stub__alpha, e2e-stub__beta and e2e-stub__Gamma.
Rotation	Coder got the new key 99 ms after the Secret change, and the next turn showed the new hash. An annotation-only change left updated_at unchanged.
Refusals (P4 a to f)	CredentialNotOptedIn, CredentialRefused, CredentialDestinationNotAllowed, SlugConflict (the other config unchanged), MCPServersNotAllowed, ForceOnNotAllowed. No Coder config for a, b, c, e, f.
Kill switch	A dashboard disable gives DisabledExternally, and Coder stays disabled. A displayName edit enables it again.
URL change, both orders	The chat reached only the intended Service, with a matching key hash.
Access	groups: []: a member's chat gets 400. [Everyone]: 201.
Admission policy	Status patches by an impersonated system:masters user and by the Kind admin are denied with the policy message. The controller still reconciles.
Delete, namespace delete	Coder answers 404 after the delete. In a namespace deletion, a second CR releases with ControlPlaneGone (7 s), and the namespace goes (17 s).

For P4 (e), unlicensed Coder allows one organization, so the run listed [no-such-org] instead. The dogfood found one how-to mismatch (the reason after a restored opt-in), which this PR fixes. The screenshots and the recording are in the evidence comment below.

Validation

• Local gates on this head: make verify-vendor, make build, make lint, GOFLAGS=-mod=vendor go tool govulncheck ./..., make test, make test-integration, go test -race ./internal/controller/, and make docs-check pass. make codegen, make manifests, make build-installer and make docs-reference leave no diff. actionlint passes.
• TestSetupControllersStartsEveryController (S18) now also needs a CoderMCPServer to get its finalizer and ControlPlaneNotReady, which proves the registration. A mutation that removes the registration fails it.
• A new case in TestCoderMCPServerControlPlaneAndOptIn: a listed name that resolves to the object's organization ID is allowed (IDs are compared, not names). A mutation to a name compare fails it.
• bash ./hack/e2e-workspace-lifecycle_test.sh times out locally under host load, also on unchanged main. CI runs it.

Size

451 hand-written changed lines (300 of them docs) and 740 generated (dist/install.yaml, the CRDs, role.yaml, the kustomization, the reference pages).

Follow-ups

• The Argo CD and Flux health rules for CoderMCPServer come in the next PR, as 🤖 docs: add GitOps health rules for CoderTemplateTest #212 did for CoderTemplateTest.
• 🤖 fix: hold a deleted CoderControlPlane while AI Gateway keys and providers still use it #362 (part 1 of Namespace deletion leaves AI Gateway keys and AI providers in Coder #353) holds a deleted CoderControlPlane while CoderAIGatewayKey and CoderAIProvider objects still use it. It does not cover CoderMCPServer. A control plane deletion can therefore leave MCP server configs in Coder. The how-to says to delete CoderMCPServer objects first. Follow-up to Namespace deletion leaves AI Gateway keys and AI providers in Coder #353: add CoderMCPServer to controlPlaneDependents.
• Ownership proof for Coder IDs recorded in controller status (D11 B) #372: an ownership proof for Coder IDs in controller status (plan D11 B).
• CoderMCPServer delete and RBAC test follow-ups #378: delete path and RBAC test follow-ups from the M7, S9 and S11 assessments.
• Each new CR logs one "Operation cannot be fulfilled" error when it adds its finalizer. The controller retries it with no effect.
• Plan step M10 adds the Kind E2E phases, and M11 the tool lists. CoderMCPServer CRD #155 stays open until then.

Refs #155

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high • Cost: $220.71

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-14T18:05:59.209988Z	9930bc7	Manual request
🔒 Security Review	✅ Completed 2026-10-14T17:55:27.167602Z	9930bc7	Manual request

Security findings

Advisory findings (1)

• 🟡 Verify MCP ownership instead of trusting writable status · Medium

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ThomasK33]

@codex security review

[ThomasK33]

Dogfood evidence (plan section 8)

Images built from 091c7fcf9a0f8f75867545a8c2a53558b2715417, which has the same controller code as this PR head. Private Kind cluster coder-k8s-mcp-dogfood (kind v0.26.0, kindest/node v1.32.0), Coder v2.37.2, no license. For the operator image and the stub image, the running container image ID equals the built image ID. All keys were synthetic and never printed. Hash checks print only "match" or "no match".

Dashboard: the managed server (step 5)

Chat with the server selected (step 6)

Kill switch: disabled in the dashboard (step 9)

After the delete (step 13)

Recording of the whole run

Rendered from the asciinema cast with idle gaps capped at 3 s (4 min 48 s, the run took about 14 min).

run-small.mp4

Step results

Step	Check	Result	Timing
Setup 1-5	cluster, CNPG, CCP, images, port-forward, token header 0600, stub (one pod, Services mcp-stub, mcp-stub-2), openai-compat provider + model	PASS	cluster 44 s, CCP Ready ~1 min
1	CCP opt-in organizations: [coder]	PASS
2	Secret, no trailing newline, label + annotation	PASS
3	apply CR (api_key, X-Api-Key, Everyone) -> Ready	PASS	233 ms
4 / P1	Coder GET: slug, url, enabled, has_api_key; ACL Everyone read only; key count in CR JSON and operator logs = 0	PASS
5	dashboard list + server page at 1440 and 390 px	PASS
6 / P2	dashboard chat with server selected, "stub answer"; key hash match; LLM got e2e-stub__alpha, __beta, __Gamma	PASS
7 / P3	rotation: Coder write after Secret change, next turn new hash match, old no match; annotation-only change keeps updated_at; both keys count 0 in logs and CR	PASS	Coder write 99 ms after the patch
8 / P4 a	unlabeled Secret -> CredentialNotOptedIn	PASS	<1 s
8 / P4 b	operator token Secret -> CredentialRefused	PASS	<1 s
8 / P4 b extra	same Secret with label + annotation	INCONCLUSIVE (CCP controller removes the label within seconds; reason stayed CredentialRefused)
8 / P4 c	url other.invalid on the P1 Secret -> CredentialDestinationNotAllowed	PASS	<1 s
8 / P4 d	slug e2e-taken created via API -> SlugConflict; its updated_at unchanged; deleting ref-d keeps it	PASS	<1 s
8 / P4 e	org not listed (CCP list set to [no-such-org], second org is Premium-gated: 403) -> MCPServersNotAllowed, no config	PASS	<1 s
8 / P4 f	force_on without allowForceOn -> ForceOnNotAllowed	PASS	<1 s
8	no Coder config for a, b, c, e, f; e2e-stub unchanged	PASS
How-to	opt-in withdrawal disables the existing server (enabled=false, key kept); stays disabled after restore; spec edit re-enables	PASS (see mismatch 1)
9 / P7	dashboard disable -> after CR annotation DisabledExternally, Coder stays enabled=false; displayName edit -> enabled again	PASS	annotation -> reason 117 ms; edit -> Ready 230 ms
10 / P5 order 1	url first: CredentialDestinationNotAllowed, Coder URL and updated_at unchanged, still enabled; then origin -> URL mcp-stub-2, chat reached mcp-stub-2 only, key match	PASS	origin -> Ready 199 ms
10 / P5 order 2	origin first (no write), then url -> Coder URL mcp-stub, chat reached mcp-stub only, key match; old origin removed, still Ready	PASS	url -> Ready 432 ms
11 / P6	groups [] -> ACL empty, member chat 400 "One or more MCP server IDs are invalid or disabled."; [Everyone] -> 201	PASS
Admission	config/admission applied; status patch as impersonated system:masters user and as kind admin denied with the policy message; configID unchanged; spec edit -> Ready; policy deleted	PASS	policy active ~2 s
13 / P9 a	delete CR -> Coder GET 404; dashboard list without the server	PASS	167 ms
P9 b	namespace deletion with CR keeper alive: finalizer released (ControlPlaneGone, log has slug + configID), namespace gone	PASS	keeper gone +7 s, namespace +17 s

Step 12 and P8 (tool lists) are M11 only and were skipped.

[chatgpt-codex-connector]

🛡️ Codex Security Review

Here are some automated security review suggestions for this pull request.

Reviewed commit: 9930bc719b

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 9930bc719b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".