Skip to content
FastMCP Server icon
v1.7.6App: v0.11.2Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

FastMCP Server

A Helm chart for deploying FastMCP Server on Kubernetes using the official docker.io/helmforge/fastmcp-server image. Dynamically loads MCP tools, resources, prompts, and knowledge bases from inline ConfigMaps, S3-compatible storage, or Git repositories.

Features

  • Multi-source loading with merge precedence: Inline > S3 > Git
  • Bearer token and JWT authentication via FastMCP
  • Knowledge base files served as MCP resources
  • Extra pip packages installed at startup
  • Built-in Web UI dashboard at /ui
  • Prometheus metrics with ServiceMonitor support
  • Structured JSON logging for log aggregation
  • Dedicated health endpoints (/healthz, /readyz, /startupz) with readiness using /healthz by default
  • Diagnostic endpoint at /debug/info
  • Init container pattern for source pre-sync
  • Strict loading mode for fail-fast on errors
  • Gateway API HTTPRoute support for modern Kubernetes ingress
  • Dual-stack Service options for IPv4/IPv6 clusters
  • Restricted pod defaults with service account token automount disabled

Security Scan: fastmcp-server

Framework Score
MITRE + NSA + SOC2 90.90909%

Security posture: acceptable for the scanned controls. Operators remain responsible for authenticating public endpoints and reviewing executable source content.

Quick Start

helm install fastmcp-server oci://ghcr.io/helmforgedev/helm/fastmcp-server

With inline tools:

helm install fastmcp-server oci://ghcr.io/helmforgedev/helm/fastmcp-server \
  --set-file sources.inline.tools.greet\.py=examples/tools/greet.py

With bearer authentication:

helm install fastmcp-server oci://ghcr.io/helmforgedev/helm/fastmcp-server \
  --set auth.type=bearer \
  --set auth.bearer.token=my-secret-token

Configuration

Inline Tools

Define Python tool files directly in values.yaml:

sources:
  inline:
    tools:
      greet.py: |
        def greet(name: str) -> str:
            """Greet someone by name."""
            return f"Hello, {name}!"
      math_ops.py: |
        def add(a: float, b: float) -> float:
            """Add two numbers."""
            return a + b
    resources:
      status.py: |
        import json
        RESOURCE_URI = "status://server"
        def get_status() -> str:
            """Server status."""
            return json.dumps({"status": "healthy"}, indent=2)
    prompts:
      summarize.py: |
        def summarize(text: str) -> str:
            """Summarize text."""
            return f"Please summarize:\n\n{text}"
    knowledge:
      overview.md: |
        # Product Overview
        Context document for the AI assistant.

S3 Source

Load tools from an S3-compatible bucket (AWS S3, MinIO, Cloudflare R2):

sources:
  s3:
    enabled: true
    endpoint: "https://minio.example.com"
    bucket: mcp-tools
    region: us-east-1
    prefix: production
    accessKey: minioadmin
    secretKey: minioadmin

Or with an existing secret:

sources:
  s3:
    enabled: true
    bucket: mcp-tools
    existingSecret: my-s3-credentials
    existingSecretAccessKeyKey: access-key
    existingSecretSecretKeyKey: secret-key

Git Source

Clone tools from a Git repository at startup:

sources:
  git:
    enabled: true
    repository: "https://github.com/your-org/mcp-tools.git"
    branch: main
    path: ""
    token: ghp_xxx  # for private repos

Authentication

Bearer token:

auth:
  type: bearer
  bearer:
    token: my-secret-token

JWT:

auth:
  type: jwt
  jwt:
    issuer: "https://auth.example.com"
    audience: "mcp-server"
    jwksUri: "https://auth.example.com/.well-known/jwks.json"

Observability

Enable Prometheus metrics and ServiceMonitor:

metrics:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s

Structured JSON logging:

server:
  logFormat: json

Gateway API

Expose only the MCP endpoint through a Gateway API HTTPRoute:

gatewayAPI:
  enabled: true
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - mcp.example.com
  paths:
    - type: PathPrefix
      value: /mcp

For long-lived streamable HTTP clients behind NGINX-style proxies, keep proxy buffering and caching disabled and use read/send timeouts long enough for MCP sessions.

Dual-Stack Service

On dual-stack clusters, request both IP families for the Service:

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

Init Container Pattern

Pre-sync sources before the server starts:

initSync:
  enabled: true

Production Example

server:
  name: production-mcp
  logLevel: WARNING
  logFormat: json
  strictLoading: true

auth:
  type: bearer
  bearer:
    existingSecret: mcp-auth

sources:
  s3:
    enabled: true
    bucket: mcp-production
    existingSecret: mcp-s3-credentials
  inline:
    knowledge:
      runbook.md: |
        # Operations Runbook
        Emergency procedures for the production environment.

extraPipPackages:
  - requests
  - pandas

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

initSync:
  enabled: true

ingress:
  enabled: true
  ingressClassName: nginx
  hosts:
    - host: mcp.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts:
        - mcp.example.com
      secretName: mcp-tls

gatewayAPI:
  enabled: true
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - mcp.example.com
  paths:
    - type: PathPrefix
      value: /mcp

persistence:
  enabled: true
  size: 5Gi

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

podSecurityContext:
  runAsUser: 1000
  runAsGroup: 1000
  runAsNonRoot: true
  fsGroup: 1000
  fsGroupChangePolicy: OnRootMismatch
  seccompProfile:
    type: RuntimeDefault

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL
  runAsUser: 1000
  runAsGroup: 1000
  runAsNonRoot: true
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | namespaceOverride | "" | Override namespace for chart-managed namespaced resources | | image.repository | docker.io/helmforge/fastmcp-server | Container image | | image.tag | 0.11.2 | Image tag | | server.name | fastmcp-server | Server name in MCP responses | | server.port | 8000 | HTTP port | | server.path | /mcp | MCP endpoint path | | server.logLevel | INFO | Log level | | server.logFormat | text | Log format: text or json | | server.strictLoading | false | Fail on boot if any component has errors | | ui.enabled | true | Enable Web UI at /ui | | metrics.enabled | false | Enable Prometheus metrics at /metrics | | metrics.serviceMonitor.enabled | false | Create ServiceMonitor CRD | | auth.type | none | Authentication: none, bearer, jwt | | sources.inline.tools | {} | Inline Python tool files | | sources.inline.resources | {} | Inline Python resource files | | sources.inline.prompts | {} | Inline Python prompt files | | sources.inline.knowledge | {} | Inline knowledge base files | | sources.s3.enabled | false | Enable S3 source | | sources.s3.bucket | "" | S3 bucket name | | sources.git.enabled | false | Enable Git source | | sources.git.repository | "" | Git repository HTTPS URL | | extraPipPackages | [] | Extra pip packages at startup | | initSync.enabled | false | Run source sync as init container | | persistence.enabled | false | Enable persistent workspace | | ingress.enabled | false | Enable ingress | | gatewayAPI.enabled | false | Create Gateway API HTTPRoute | | service.ipFamilyPolicy | "" | Optional Service IP family policy | | service.ipFamilies | [] | Optional Service IP families | | serviceAccount.automountServiceAccountToken | false | Mount Kubernetes API token into pods | | networkPolicy.enabled | false | Enable NetworkPolicy |

See values.yaml for the full configuration reference.

Architecture and Operations

Connecting MCP Clients

After deploying the chart, connect AI assistants to the MCP endpoint.

Claude Code

Add to your Claude Code settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

The URL is your ingress host + the server.path value (default /mcp).

Codex (VS Code Extension)

Add to your Codex configuration (~/.codex/config.toml):

[mcp_servers.my-mcp-server]
enabled = true
url = "https://mcp.example.com/mcp"

[mcp_servers.my-mcp-server.http_headers]
Authorization = "Bearer <your-token>"

Port-Forward (Development)

For local testing without ingress:

kubectl port-forward svc/fastmcp-server 8000:8000

Then use http://localhost:8000/mcp as the URL (no auth if auth.type=none).

Examples

Troubleshooting

Check rollout status and application logs first:

RELEASE=fastmcp-server
NAMESPACE=default
DEPLOYMENT=$(kubectl get deployment -n "$NAMESPACE" \
  -l "app.kubernetes.io/instance=$RELEASE,app.kubernetes.io/name=fastmcp-server" \
  -o jsonpath='{.items[0].metadata.name}')
kubectl rollout status deployment/"$DEPLOYMENT" -n "$NAMESPACE"
kubectl logs deployment/"$DEPLOYMENT" -n "$NAMESPACE"

When initSync.enabled=true, inspect the source synchronization container:

kubectl logs deployment/"$DEPLOYMENT" -c source-sync -n "$NAMESPACE"

If the pod is healthy but clients cannot connect, port-forward the Service and test the configured MCP path directly:

SERVICE=$(kubectl get service -n "$NAMESPACE" \
  -l "app.kubernetes.io/instance=$RELEASE,app.kubernetes.io/name=fastmcp-server" \
  -o jsonpath='{.items[0].metadata.name}')
SERVICE_PORT="${SERVICE_PORT:-8000}" # Match service.port.
MCP_PATH="${MCP_PATH:-/mcp}" # Match server.path.
kubectl port-forward service/"$SERVICE" \
  "$SERVICE_PORT:$SERVICE_PORT" -n "$NAMESPACE"
curl "http://127.0.0.1:$SERVICE_PORT/healthz"
# A bare GET is expected to return HTTP 406 without an Accept:
# text/event-stream header; that response confirms the route is reachable.
curl -i "http://127.0.0.1:$SERVICE_PORT$MCP_PATH"

Authentication failures usually indicate that the client header, referenced Secret name, or configured Secret key does not match the selected auth mode. Source-loading failures are reported in the application or source-sync logs; also verify network egress and the Git, S3, or JWKS endpoint independently.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  client[MCP client] --> route[Ingress or HTTPRoute optional]
  route --> service[FastMCP Service]
  service --> pod[FastMCP pod]
  inline[Inline ConfigMaps] -. read-only mounts .-> pod
  secrets[Existing or chart-managed Secrets] -. credentials .-> pod
  s3[S3-compatible storage optional] -. source sync .-> pod
  git[Git repository optional] -. source sync .-> pod
  pod --> workspace[Workspace emptyDir or PVC]
  pod --> metrics[Metrics endpoint optional]
Official Contractvalues.schema.json

FastMCP Server Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

141 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override the full release name used in resource names

Namespace Override(1)

ParameterTypeDefaultDescription
namespaceOverridestring-Override the namespace for chart-managed namespaced resources

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Server(6)

ParameterTypeDefaultDescription
server.namestring-Server name announced in MCP responses
server.portinteger-HTTP port
server.pathstring-MCP endpoint URL path
server.logLevelstring-Log level
Allowed:DEBUGINFOWARNINGERROR
server.logFormatstring-Log output format
Allowed:textjson
server.strictLoadingboolean-Fail on boot if any tool/resource has errors

Ui(1)

ParameterTypeDefaultDescription
ui.enabledboolean-Chart configuration parameter

Metrics & Observability(4)

ParameterTypeDefaultDescription
metrics.enabledboolean-Chart configuration parameter
metrics.serviceMonitor.enabledboolean-Chart configuration parameter
metrics.serviceMonitor.intervalstring-Chart configuration parameter
metrics.serviceMonitor.labelsobject-Chart configuration parameter

Rate Limiting(2)

ParameterTypeDefaultDescription
rateLimiting.defaultstring-Default rate limit for all tools (e.g., 100/min)
rateLimiting.perToolobject-Per-tool rate limits (key = TOOL_NAME_UPPER)

Caching(2)

ParameterTypeDefaultDescription
caching.enabledboolean-Chart configuration parameter
caching.maxSizeinteger-Max cache entries per tool

Sandboxing(2)

ParameterTypeDefaultDescription
sandboxing.maxMemoryMbinteger-Default max memory per tool call (MB)
sandboxing.maxOutputSizeKbinteger-Default max output size per tool call (KB)

Authentication(7)

ParameterTypeDefaultDescription
auth.typestring-Authentication type
Allowed:nonebearerjwt
auth.bearer.tokenstring-Chart configuration parameter
auth.bearer.existingSecretstring-Chart configuration parameter
auth.bearer.existingSecretKeystring-Chart configuration parameter
auth.jwt.issuerstring-Chart configuration parameter
auth.jwt.audiencestring-Chart configuration parameter
auth.jwt.jwksUristring-Chart configuration parameter

Sources(21)

ParameterTypeDefaultDescription
sources.inline.toolsobject-Python tool files (key=filename, value=content)
sources.inline.resourcesobject-Python resource files
sources.inline.promptsobject-Python prompt files
sources.inline.knowledgeobject-Knowledge base files
sources.s3.enabledboolean-Chart configuration parameter
sources.s3.endpointstring-Chart configuration parameter
sources.s3.bucketstring-Chart configuration parameter
sources.s3.regionstring-Chart configuration parameter
sources.s3.prefixstring-Chart configuration parameter
sources.s3.accessKeystring-Chart configuration parameter
sources.s3.secretKeystring-Chart configuration parameter
sources.s3.existingSecretstring-Chart configuration parameter
sources.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
sources.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
sources.git.enabledboolean-Chart configuration parameter
sources.git.repositorystring-Chart configuration parameter
sources.git.branchstring-Chart configuration parameter
sources.git.pathstring-Chart configuration parameter
sources.git.tokenstring-Chart configuration parameter
sources.git.existingSecretstring-Chart configuration parameter
sources.git.existingSecretTokenKeystring-Chart configuration parameter

Extra Pip Packages(1)

ParameterTypeDefaultDescription
extraPipPackagesarray-Extra pip packages to install at startup

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystring-Optional Service IP family policy
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Optional Service IP families

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Gateway API(5)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Chart configuration parameter
gatewayAPI.annotationsobject-Chart configuration parameter
gatewayAPI.parentRefsarray-Chart configuration parameter
gatewayAPI.hostnamesarray-Chart configuration parameter
gatewayAPI.pathsarray-Chart configuration parameter

Health Probes(21)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.httpGet.pathstring-Chart configuration parameter
probes.startup.httpGet.portintegerstring-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.httpGet.pathstring-Chart configuration parameter
probes.liveness.httpGet.portintegerstring-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.httpGet.pathstring-Chart configuration parameter
probes.readiness.httpGet.portintegerstring-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledboolean-Chart configuration parameter
persistence.sizestring-Chart configuration parameter
persistence.storageClassstring-Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring-Chart configuration parameter

Init Sync(1)

ParameterTypeDefaultDescription
initSync.enabledboolean-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Network Policy(2)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.extraEgressarray-Additional NetworkPolicy egress rules

Pdb(2)

ParameterTypeDefaultDescription
pdb.enabledboolean-Chart configuration parameter
pdb.minAvailableinteger-Chart configuration parameter

Autoscaling(5)

ParameterTypeDefaultDescription
autoscaling.enabledboolean-Chart configuration parameter
autoscaling.minReplicasinteger-Chart configuration parameter
autoscaling.maxReplicasinteger-Chart configuration parameter
autoscaling.targetCPUUtilizationPercentageinteger-Chart configuration parameter
autoscaling.targetMemoryUtilizationPercentageintegerstring-Chart configuration parameter

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Number of replicas (ignored when autoscaling is enabled)

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Chart configuration parameter
resources.requests.memorystringnumber-Chart configuration parameter
resources.limits.cpustringnumber-Chart configuration parameter
resources.limits.memorystringnumber-Chart configuration parameter

Pod Security(7)

ParameterTypeDefaultDescription
podSecurityContext.runAsUserinteger-Chart configuration parameter
podSecurityContext.runAsGroupinteger-Chart configuration parameter
podSecurityContext.runAsNonRootboolean-Chart configuration parameter
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
podSecurityContext.seccompProfile.localhostProfilestring-Chart configuration parameter

Container Security(7)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.addarray-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.runAsGroupinteger-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Env(1)

ParameterTypeDefaultDescription
extraEnvarray-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter