@@ -51,6 +51,8 @@
     "stakater",
     "coderaigatewaykey",
     "coderaigatewaykeys",
+    "codermcpserver",
+    "codermcpservers",
     "coderaiprovider",
     "coderaiproviders",
     "codertemplatetest",
 
@@ -87,6 +87,7 @@ jobs:
               - 'internal/controller/codertemplatetest*'
               - 'internal/controller/coderaiprovider*'
               - 'internal/controller/coderaigatewaykey*'
+              - 'internal/controller/codermcpserver*'
               - 'internal/controller/owned_secret.go'
               - 'internal/controller/reserved_secret_names.go'
               - 'internal/controller/credential_checks.go'
@@ -172,22 +173,6 @@ jobs:
             exit 1
           fi
 
-      - name: Verify the dormant CoderMCPServer CRD is not installed
-        # Remove this step when the CoderMCPServer controller ships (#155).
-        run: |
-          # grep exits 1 when nothing matches. Any other status (for example a missing file) fails the step.
-          status=0
-          # The third pattern matches the CRD path entry in config/default/kustomization.yaml.
-          grep -n -E '^[[:space:]]+kind: CoderMCPServer$|codermcpservers\.coder\.com|coder\.com_codermcpservers\.yaml' \
-            dist/install.yaml config/default/kustomization.yaml config/crd/bases/*.yaml || status=$?
-          if [[ "${status}" -eq 0 ]]; then
-            echo "assertion failed: the CoderMCPServer CRD must not ship before its controller" >&2
-            exit 1
-          elif [[ "${status}" -ne 1 ]]; then
-            echo "assertion failed: the CoderMCPServer CRD guard could not read the install manifests (grep exit ${status})" >&2
-            exit 1
-          fi
-
       - name: Verify the dormant CoderWorkspacePool CRD is not installed
         # Remove this step when the CoderWorkspacePool controller ships (#153).
         run: |
 
@@ -127,8 +127,7 @@ type CoderControlPlaneSpec struct {
 
 	// MCPServers configures CoderMCPServer objects that use this control
 	// plane. Removing it disables in Coder each server config that a
-	// CoderMCPServer created through this control plane. It has no effect
-	// yet: the CoderMCPServer controller is not shipped.
+	// CoderMCPServer created through this control plane.
 	// +optional
 	MCPServers *MCPServersSpec `json:"mcpServers,omitempty"`
 
 
@@ -34,9 +34,6 @@ type MCPServersSpec struct {
 	// enabled: false, and then changes nothing else. After the organization
 	// is listed again, a spec edit enables the server. Deleting a
 	// CoderMCPServer still deletes the config it created.
-	//
-	// This field has no effect yet: the CoderMCPServer controller is not
-	// shipped.
 	// +kubebuilder:validation:MinItems=1
 	// +kubebuilder:validation:MaxItems=64
 	// +kubebuilder:validation:items:MinLength=1
@@ -50,9 +47,6 @@ type MCPServersSpec struct {
 	// without that user's choice. When false (the default), such objects
 	// create and change nothing, and a server config that one of them
 	// created is disabled in Coder, as for a removed organization.
-	//
-	// This field has no effect yet: the CoderMCPServer controller is not
-	// shipped.
 	// +optional
 	AllowForceOn bool `json:"allowForceOn,omitempty"`
 }
@@ -76,7 +70,7 @@ type CoderMCPServerSpec struct {
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="organization is immutable"
 	Organization string `json:"organization"`
 	// Slug is the Coder slug of the config, unique in its organization. The
-	// model sees the server's tools as <slug>__<tool>.
+	// model sees the server's tools as `<slug>__<tool>`.
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=32
 	// +kubebuilder:validation:Pattern=`^[a-z0-9]+(-[a-z0-9]+)*$`
@@ -175,7 +169,7 @@ type CoderMCPServerAuth struct {
 }
 
 // CoderMCPServerAPIKeyAuth sends one Secret value in one header. Coder sends
-// the value as it is, so a bearer token is stored as "Bearer <token>".
+// the value as it is, so a bearer token is stored as `Bearer <token>`.
 type CoderMCPServerAPIKeyAuth struct {
 	// Header is the HTTP header name.
 	// +kubebuilder:validation:MinLength=1
@@ -277,7 +271,7 @@ type CoderMCPServerAccess struct {
 // from it.
 type CoderMCPServerCredentialStatus struct {
 	// Field names the credential: apiKey, oauth2ClientSecret, or
-	// header:<name>.
+	// `header:<name>`.
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=160
 	Field string `json:"field"`
 
@@ -5,6 +5,7 @@
 # config/default does not apply this file. Apply it with
 # `kubectl apply -f config/admission/`. If the operator runs as another
 # ServiceAccount, change the user name in the expression first.
+# docs/how-to/manage-mcp-servers.md describes the policy.
 apiVersion: admissionregistration.k8s.io/v1
 kind: ValidatingAdmissionPolicy
 metadata:
 
@@ -1400,8 +1400,7 @@ spec:
                 description: |-
                   MCPServers configures CoderMCPServer objects that use this control
                   plane. Removing it disables in Coder each server config that a
-                  CoderMCPServer created through this control plane. It has no effect
-                  yet: the CoderMCPServer controller is not shipped.
+                  CoderMCPServer created through this control plane.
                 properties:
                   allowForceOn:
                     description: |-
@@ -1410,9 +1409,6 @@ spec:
                       without that user's choice. When false (the default), such objects
                       create and change nothing, and a server config that one of them
                       created is disabled in Coder, as for a removed organization.
-
-                      This field has no effect yet: the CoderMCPServer controller is not
-                      shipped.
                     type: boolean
                   organizations:
                     description: |-
@@ -1427,9 +1423,6 @@ spec:
                       enabled: false, and then changes nothing else. After the organization
                       is listed again, a spec edit enables the server. Deleting a
                       CoderMCPServer still deletes the config it created.
-
-                      This field has no effect yet: the CoderMCPServer controller is not
-                      shipped.
                     items:
                       maxLength: 32
                       minLength: 1
 
@@ -382,7 +382,7 @@ spec:
               slug:
                 description: |-
                   Slug is the Coder slug of the config, unique in its organization. The
-                  model sees the server's tools as <slug>__<tool>.
+                  model sees the server's tools as `<slug>__<tool>`.
                 maxLength: 32
                 minLength: 1
                 pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
@@ -513,7 +513,7 @@ spec:
                     field:
                       description: |-
                         Field names the credential: apiKey, oauth2ClientSecret, or
-                        header:<name>.
+                        `header:<name>`.
                       maxLength: 160
                       minLength: 1
                       type: string
 
@@ -6,6 +6,7 @@ resources:
   - ../crd/bases/coder.com_coderaigatewaykeys.yaml
   - ../crd/bases/coder.com_coderaiproviders.yaml
   - ../crd/bases/coder.com_codercontrolplanes.yaml
+  - ../crd/bases/coder.com_codermcpservers.yaml
   - ../crd/bases/coder.com_coderprovisioners.yaml
   - ../crd/bases/coder.com_codertemplatetests.yaml
   - ../crd/bases/coder.com_coderworkspaceproxies.yaml
 
@@ -86,6 +86,7 @@ rules:
   resources:
   - coderaigatewaykeys
   - coderaiproviders
+  - codermcpservers
   verbs:
   - get
   - list
@@ -97,6 +98,7 @@ rules:
   - coderaigatewaykeys/finalizers
   - coderaiproviders/finalizers
   - codercontrolplanes/finalizers
+  - codermcpservers/finalizers
   - coderprovisioners/finalizers
   - codertemplatetests/finalizers
   - coderworkspaceproxies/finalizers
@@ -107,6 +109,7 @@ rules:
   resources:
   - coderaigatewaykeys/status
   - coderaiproviders/status
+  - codermcpservers/status
   verbs:
   - get
   - update
@@ -135,12 +138,6 @@ rules:
   - get
   - patch
   - update
-- apiGroups:
-  - coder.com
-  resources:
-  - codermcpservers
-  verbs:
-  - list
 - apiGroups:
   - coder.com
   resources:
 
@@ -0,0 +1,46 @@
+# Manages one MCP server config in a Coder organization. See
+# docs/how-to/manage-mcp-servers.md.
+#
+# Prerequisites:
+# - CoderControlPlane codercontrolplane-sample with status.operatorAccessReady
+#   true and spec.mcpServers.organizations listing coder.
+# - Replace the placeholder key below. Never commit a real key.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: example-mcp-key
+  namespace: coder
+  labels:
+    coder.com/credential: "true"
+  annotations:
+    # The origin of spec.url. The operator sends the key to no other origin.
+    coder.com/credential-destinations: https://mcp.example.com
+type: Opaque
+stringData:
+  api-key: replace-with-the-mcp-server-key
+---
+apiVersion: coder.com/v1alpha1
+kind: CoderMCPServer
+metadata:
+  name: example
+  namespace: coder
+spec:
+  controlPlaneRef:
+    name: codercontrolplane-sample
+  # Immutable: Coder cannot move a config to another organization.
+  organization: coder
+  # Immutable: the model sees the tools as example__<tool>.
+  slug: example
+  displayName: Example
+  url: https://mcp.example.com/mcp
+  auth:
+    type: api_key
+    apiKey:
+      header: X-Api-Key
+      secretRef:
+        name: example-mcp-key
+        key: api-key
+  # Exactly these groups can read the server. Every sync removes other
+  # entries, also user grants added in the Coder dashboard.
+  access:
+    groups: [Everyone]