For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Configure your MCP server to read additional environment variables from a Kubernetes secret.

You can bootstrap your MCP server with additional environment variables that the MCP server needs to run properly. These environment variables are typically defined in an .env file.

You can use the kmcp secret command to store these environment variables in a Kubernetes secret and to automatically configure the MCP server to mount that secret during the MCP server deployment.

The name and namespace of the Kubernetes secret that you want to create is defined in the kmcp.yaml file of your project.

Prerequisites

• Create a FastMCP or MCP Go project with a sample MCP server and tool.
• Install the kmcp controller in a local kind cluster to manage the lifecycle of MCP servers in your cluster.

Store environment variables in a Kubernetes secret

1. Review the kmcp.yaml configuration of your MCP project. The default kmcp.yaml file includes a secrets section that defines multiple environments, such as staging, production, and local. Each environment defines the name and the namespace of the Kubernetes secret that you want to use. Note that all environments are currently disabled.

   cat my-mcp-server/kmcp.yaml

   Example output:

   name: my-mcp-server
   framework: fastmcp-python
   version: 0.1.0
   description: MCP server built with fastmcp-python
   secrets:
       local:
           enabled: false
           provider: env
           file: .env.local
       production:
           enabled: false
           provider: kubernetes
           secretName: my-mcp-server-secrets-production
           namespace: default
       staging:
           enabled: false
           provider: kubernetes
           secretName: my-mcp-server-secrets-staging
           namespace: default

2. Enable the staging environment by setting the secret.staging.enabled field to true. You can optionally change the name and namespace of the Kubernetes secret that you want to use with your MCP server. However, keep in mind that the secret must be in the same namespace where the MCP server is deployed.

   ...
   secrets:
       local:
           enabled: false
           provider: env
           file: .env.local
       production:
           enabled: false
           provider: kubernetes
           secretName: my-mcp-server-secrets-production
           namespace: default
       staging:
           enabled: true
           provider: kubernetes
           secretName: my-mcp-server-secrets-staging
           namespace: default

3. Create an .env.staging file in your MCP project that defines additional environment variables that you want to provide to your MCP server.

   cat << EOF > my-mcp-server/.env.staging
   # .env.staging
   API_KEY=your-api-key-here
   DATABASE_URL=postgresql://user:pass@host:5432/db
   EOF

4. Create the Kubernetes secret in your kind cluster by using the secret defintion from the kmcp.yaml file and the environment variables from the .env.staging file. Note that this step is not required when you plan to run your MCP server locally only.

   kmcp secrets sync staging --from-file my-mcp-server/.env.staging --project-dir my-mcp-server

5. Verify that the Kubernetes secret is created and that you can see the base64-encoded environment variables that you defined earlier.

   kubectl get secret my-mcp-server-secrets-staging -o yaml

   Example output:

   apiVersion: v1
   data:
     API_KEY: eW91ci1hcGkta2V5LWhlcmU=
     DATABASE_URL: cG9zdGdyZXNxbDovL3VzZXI6cGFzc0Bob3N0OjU0MzIvZGI=
   kind: Secret
   metadata:
     name: my-mcp-server-secrets-staging
     namespace: default
     resourceVersion: "10819"
     uid: 85...
   type: Opaque

Deploy the MCP server with your secret

1. Build a Docker image for your MCP server and load it to your kind cluster.

   kmcp build --project-dir my-mcp-server -t my-mcp-server:latest --kind-load-cluster kind

2. Deploy your MCP server and bootstrap it with the Kubernetes secret of the staging environment.

   kmcp deploy --environment staging --file my-mcp-server/kmcp.yaml --no-inspector --image my-mcp-server:latest

3. Verify that your server is up and running.

   kubectl get pods

4. Get the details of the my-mcp-server deployment. Verify that you see the reference to your Kubernetes secret in the spec.containers.envFrom section.

   kubectl get deployment my-mcp-server -o yaml

   Example output:

   ...
   template:
     metadata:
       creationTimestamp: null
       labels:
         app.kubernetes.io/instance: my-mcp-server
         app.kubernetes.io/managed-by: kmcp
         app.kubernetes.io/name: my-mcp-server
     spec:
       containers:
       ...
         envFrom:
         - secretRef:
             name: my-mcp-server-secrets-staging
         image: my-mcp-server:latest
   ...