Add the CRD reference page

Author: danbarr

.markdownlint-cli2.jsonc

@@ -1,5 +1,5 @@
 {
   "gitignore": true,
   "globs": ["**/*.md"],
-  "ignores": ["docs/toolhive/reference/cli/"],
+  "ignores": ["docs/toolhive/reference/cli/", "static/api-specs/*.md"],
 }

.vscode/settings.json

@@ -9,20 +9,7 @@
   "prettier.requireConfig": true,
   "yaml.format.proseWrap": "always",
   "css.lint.emptyRules": "ignore",
-
-  "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[mdx]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[css]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[json]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[yaml]": {
+  "[markdown][mdx][css][json][jsonc][yaml]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
 }

docs/toolhive/guides-k8s/run-mcp-k8s.md

@@ -163,6 +163,10 @@ When you apply an `MCPServer` resource, here's what happens:
 
 :::
 
+For more examples of `MCPServer` resources, see the
+[example MCP server manifests](https://github.com/stacklok/toolhive/tree/main/examples/operator/mcp-servers)
+in the ToolHive repo.
+
 ## Automatic RBAC management
 
 The ToolHive operator automatically handles RBAC (Role-Based Access Control) for
@@ -185,14 +189,13 @@ This approach provides:
 - Better security isolation between different MCPServer instances
 - Support for multi-tenant deployments across different namespaces
 
-For more examples of `MCPServer` resources, see the
-[example MCP server manifests](https://github.com/stacklok/toolhive/tree/main/examples/operator/mcp-servers)
-in the ToolHive repo.
-
 ## Customize server settings
 
 You can customize the MCP server by adding additional fields to the `MCPServer`
-resource. Here are some common configurations.
+resource. The full specification is available in the
+[Kubernetes CRD reference](../reference/crd-spec.mdx).
+
+Below are some common configurations.
 
 ### Customize the MCP server pod
 
@@ -363,56 +366,19 @@ For more details about a specific MCP server:
 kubectl -n <NAMESPACE> describe mcpserver <NAME>
 ```
 
-## Configuration reference
-
-### MCPServer spec
-
-| Field               | Description                                     | Required | Default |
-| ------------------- | ----------------------------------------------- | -------- | ------- |
-| `image`             | Container image for the MCP server              | Yes      | -       |
-| `transport`         | Transport method (stdio or sse)                 | No       | stdio   |
-| `port`              | Port to expose the MCP server on                | No       | 8080    |
-| `targetPort`        | Port to use for the MCP server (for SSE)        | No       |         |
-| `args`              | Additional arguments to pass to the MCP server  | No       | -       |
-| `env`               | Environment variables to set in the container   | No       | -       |
-| `resources`         | Resource requirements for the container         | No       | -       |
-| `secrets`           | References to secrets to mount in the container | No       | -       |
-| `permissionProfile` | Permission profile configuration                | No       | -       |
-| `podTemplateSpec`   | Custom pod specification for the MCP server     | No       | -       |
-
-### Secrets
-
-The `secrets` field has the following parameters:
-
-- `name`: The name of the Kubernetes secret (required)
-- `key`: The key in the secret (required)
-- `targetEnvName`: The environment variable to be used when setting up the
-  secret in the MCP server (optional). If left unspecified, it defaults to the
-  key.
-
-### Permission Profiles
-
-Permission profiles can be configured in two ways:
-
-1. Using a built-in profile:
-
-   ```yaml
-   permissionProfile:
-     type: builtin
-     name: network # or "none"
-   ```
+## Next steps
 
-2. Using a ConfigMap:
+See the [Client compatibility](../reference/client-compatibility.mdx) reference
+to learn how to connect to MCP servers using different clients.
 
-   ```yaml
-   permissionProfile:
-     type: configmap
-     name: my-permission-profile
-     key: profile.json
-   ```
+## Related information
 
-The ConfigMap should contain a JSON
-[permission profile](../guides-cli/custom-permissions.mdx#create-a-custom-permission-profile).
+- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Reference for the
+  `MCPServer` Custom Resource Definition (CRD)
+- [Deploy the operator using Helm](./deploy-operator-helm.md) - Install the
+  ToolHive operator
+- [Custom permissions](../guides-cli/custom-permissions.mdx) - Configure
+  permission profiles
 
 :::important
 
@@ -425,18 +391,6 @@ visiting our [GitHub repository](https://github.com/stacklok/toolhive).
 
 :::
 
-## Next steps
-
-See the [Client compatibility](../reference/client-compatibility.mdx) reference
-to learn how to connect to MCP servers using different clients.
-
-## Related information
-
-- [Deploy the operator using Helm](./deploy-operator-helm.md) - Install the
-  ToolHive operator
-- [Custom permissions](../guides-cli/custom-permissions.mdx) - Configure
-  permission profiles
-
 ## Troubleshooting
 
 ### MCPServer resource not creating pods

docs/toolhive/reference/crd-spec.mdx

@@ -0,0 +1,11 @@
+---
+title: Kubernetes CRD reference
+description:
+  ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference.
+sidebar_position: 30
+toc_max_heading_level: 4
+---
+
+import CRDRef from '@site/static/api-specs/crd-api.md';
+
+<CRDRef />