Update wording, rewrite the Vault section

Signed-off-by: Dan Barr <[email protected]>

Author: danbarr

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

@@ -253,14 +253,25 @@ process.
 
 ### Run a server with secrets
 
-For MCP servers that require authentication tokens or other secrets, you can use
-secrets from multiple secrets managers:
+When your MCP servers require authentication tokens or other secrets, ToolHive
+supports multiple secrets management methods to fit your existing
+infrastructure. Choose the method that best suits your needs:
 
 <Tabs groupId='secret-manager' queryString='secret-manager'>
-<TabItem value='kubernetes-native' label='Kubernetes' default>
+<TabItem value='kubernetes-native' label='Kubernetes secrets' default>
 
-This example shows how to use an existing Kubernetes secret to pass a GitHub
-personal access token to the `github` MCP server.
+ToolHive can reference existing Kubernetes secrets to inject sensitive data into
+your MCP server pods as environment variables. This example demonstrates how to
+pass a GitHub personal access token to the `github` MCP server.
+
+First, create the secret. The secret must exist in the same namespace as your
+MCP server and the key must match what you specify in the `MCPServer` resource.
+
+```bash
+kubectl -n production create secret generic github-token --from-literal=token=<YOUR_TOKEN>
+```
+
+Next, define the `MCPServer` resource to reference the secret:
 
 ```yaml {13-16} title="my-mcpserver-with-secrets.yaml"
 apiVersion: toolhive.stacklok.dev/v1alpha1
@@ -281,15 +292,7 @@ spec:
       targetEnvName: GITHUB_PERSONAL_ACCESS_TOKEN
 ```
 
-First, create the secret. Note that the secret must be created in the same
-namespace as the MCP server and the key must match the one specified in the
-`MCPServer` resource.
-
-```bash
-kubectl -n production create secret generic github-token --from-literal=token=<YOUR_TOKEN>
-```
-
-Apply the MCPServer resource:
+Finally, apply the MCPServer resource:
 
 ```bash
 kubectl apply -f my-mcpserver-with-secrets.yaml
@@ -298,18 +301,27 @@ kubectl apply -f my-mcpserver-with-secrets.yaml
 </TabItem>
 <TabItem value='eso' label='External Secrets Operator'>
 
-This example shows how to use an existing Kubernetes secret created by the
-[External Secrets Operator](https://external-secrets.io/) to pass a GitHub
-personal access token to the `github` MCP server.
+[External Secrets Operator](https://external-secrets.io/) is a Kubernetes
+operator that integrates external secret management systems and syncs secrets
+into Kubernetes as native resources. This example demonstrates how to use
+ESO-managed secrets with your MCP server.
 
-:::info[Important]
+:::note
 
-Given the External Secrets Operator creates standard Kubernetes secrets based on
-external secrets, the MCP server definition will look the same as the Kubernetes
-example.
+When you use the External Secrets Operator, your MCP server definition will look
+the same as the Kubernetes-native example. This is because the External Secrets
+Operator creates standard Kubernetes secrets from external sources.
 
 :::
 
+First, create a secret using the
+[ExternalSecret resource](https://external-secrets.io/latest/api/externalsecret/).
+The exact configuration depends on your external secret management system. The
+secret must exist in the same namespace as your MCP server and the key must
+match what you specify in the `MCPServer` resource.
+
+Next, define the `MCPServer` resource to reference the secret:
+
 ```yaml {13-16} title="my-mcpserver-with-secrets-eso.yaml"
 apiVersion: toolhive.stacklok.dev/v1alpha1
 kind: MCPServer
@@ -329,83 +341,35 @@ spec:
       targetEnvName: GITHUB_PERSONAL_ACCESS_TOKEN
 ```
 
-First, create the secret by using
-[External Secrets Operator](https://external-secrets.io/latest/api/externalsecret).
-Note that the secret must be created in the same namespace as the MCP server and
-the key must match the one specified in the `MCPServer` resource.
-
-Apply the MCPServer resource:
+Finally, apply the MCPServer resource:
 
 ```bash
 kubectl apply -f my-mcpserver-with-secrets-eso.yaml
 ```
 
 </TabItem>
-<TabItem value='vault' label='Vault Secret Injection'>
-
-This example shows how to use [Vault](https://developer.hashicorp.com/vault) to
-inject secrets into the ToolHive containers for consumption.
-
-Injecting secrets using Vault is done with its agent sidecar container, but
-before you can start injecting secrets into the container there are some steps
-to do before hand. This includes setting up Vault to be able to authenticate and
-pull the necessary secrets. We will not detail here how to do this as there are
-some very helpful
-[Vault guides](https://developer.hashicorp.com/vault/tutorials/kubernetes/kubernetes-sidecar)
-on setting this up, but before we can inject secrets into the ToolHive
-containers we need to have the following:
-
-- Vault available
-- Vault configured for Kubernetes authentication
-- Vault policy created to be able to read the desired secrets
-- Vault role created that is bound to the ToolHive ProxyRunner Service Account
-  in order to enable authentication
-
-```yaml {23-33} title="my-mcpserver-with-vault-secrets-injection.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
-kind: MCPServer
-metadata:
-  name: github-vault-generic
-  namespace: toolhive-system
-spec:
-  image: ghcr.io/github/github-mcp-server:latest
-  transport: stdio
-  port: 9095
-  permissionProfile:
-    type: builtin
-    name: network
-  resources:
-    limits:
-      cpu: '100m'
-      memory: '128Mi'
-    requests:
-      cpu: '50m'
-      memory: '64Mi'
-  resourceOverrides:
-    proxyDeployment:
-      podTemplateMetadataOverrides:
-        annotations:
-          # Enable Vault Agent injection
-          vault.hashicorp.com/agent-inject: 'true'
-          vault.hashicorp.com/role: '<ROLE_NAME_CREATE_IN_VAULT>'
-
-          # Inject GitHub configuration secret
-          vault.hashicorp.com/agent-inject-secret-github-config: 'workload-secrets/data/github-mcp/config'
-          vault.hashicorp.com/agent-inject-template-github-config: |
-            {{- with secret "workload-secrets/data/github-mcp/config" -}}
-            GITHUB_PERSONAL_ACCESS_TOKEN={{ .Data.data.token }}
-            {{- end -}}
-```
-
-Apply the MCPServer resource:
-
-```bash
-kubectl apply -f my-mcpserver-with-vault-secrets-injection.yaml
-```
-
-The Vault agent sidecar will now inject secrets from the
-`workload-secrets/data/github-mcp/config` inside of Vault, into the ProxyRunner
-container.
+<TabItem value='vault' label='HashiCorp Vault'>
+
+HashiCorp Vault provides multiple integration methods for Kubernetes
+environments:
+
+1. [Vault Sidecar Agent Injector](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/injector),
+   which injects a sidecar container into your pod to fetch and renew secrets
+2. [Vault Secrets Operator](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/vso),
+   which creates Kubernetes secrets from Vault secrets (similar to the External
+   Secrets Operator)
+3. [Vault CSI Provider](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/csi),
+   which mounts secrets directly into your pod as files
+
+ToolHive supports the first two methods. When you use the Vault Secrets
+Operator, your MCP server definition will look the same as the Kubernetes-native
+example because the Vault Secrets Operator creates standard Kubernetes secrets
+from Vault.
+
+The Vault Sidecar Agent Injector requires additional configuration in your
+`MCPServer` resource to add the required annotations. For a complete example,
+see the
+[HashiCorp Vault integration tutorial](../tutorials/vault-integration.mdx).
 
 </TabItem>
 </Tabs>