Documentation

Manage secrets

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

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
    ...