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/healthzby 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
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.
|-----|---------|-------------|
| 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 SyncedVerified 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]
FastMCP Server Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Override the full release name used in resource names |
Namespace Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| namespaceOverride | string | - | Override the namespace for chart-managed namespaced resources |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Server(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| server.name | string | - | Server name announced in MCP responses |
| server.port | integer | - | HTTP port |
| server.path | string | - | MCP endpoint URL path |
| server.logLevel | string | - | Log level Allowed: DEBUGINFOWARNINGERROR |
| server.logFormat | string | - | Log output format Allowed: textjson |
| server.strictLoading | boolean | - | Fail on boot if any tool/resource has errors |
Ui(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ui.enabled | boolean | - | Chart configuration parameter |
Metrics & Observability(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| metrics.enabled | boolean | - | Chart configuration parameter |
| metrics.serviceMonitor.enabled | boolean | - | Chart configuration parameter |
| metrics.serviceMonitor.interval | string | - | Chart configuration parameter |
| metrics.serviceMonitor.labels | object | - | Chart configuration parameter |
Rate Limiting(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| rateLimiting.default | string | - | Default rate limit for all tools (e.g., 100/min) |
| rateLimiting.perTool | object | - | Per-tool rate limits (key = TOOL_NAME_UPPER) |
Caching(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| caching.enabled | boolean | - | Chart configuration parameter |
| caching.maxSize | integer | - | Max cache entries per tool |
Sandboxing(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| sandboxing.maxMemoryMb | integer | - | Default max memory per tool call (MB) |
| sandboxing.maxOutputSizeKb | integer | - | Default max output size per tool call (KB) |
Authentication(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| auth.type | string | - | Authentication type Allowed: nonebearerjwt |
| auth.bearer.token | string | - | Chart configuration parameter |
| auth.bearer.existingSecret | string | - | Chart configuration parameter |
| auth.bearer.existingSecretKey | string | - | Chart configuration parameter |
| auth.jwt.issuer | string | - | Chart configuration parameter |
| auth.jwt.audience | string | - | Chart configuration parameter |
| auth.jwt.jwksUri | string | - | Chart configuration parameter |
Sources(21)
| Parameter | Type | Default | Description |
|---|---|---|---|
| sources.inline.tools | object | - | Python tool files (key=filename, value=content) |
| sources.inline.resources | object | - | Python resource files |
| sources.inline.prompts | object | - | Python prompt files |
| sources.inline.knowledge | object | - | Knowledge base files |
| sources.s3.enabled | boolean | - | Chart configuration parameter |
| sources.s3.endpoint | string | - | Chart configuration parameter |
| sources.s3.bucket | string | - | Chart configuration parameter |
| sources.s3.region | string | - | Chart configuration parameter |
| sources.s3.prefix | string | - | Chart configuration parameter |
| sources.s3.accessKey | string | - | Chart configuration parameter |
| sources.s3.secretKey | string | - | Chart configuration parameter |
| sources.s3.existingSecret | string | - | Chart configuration parameter |
| sources.s3.existingSecretAccessKeyKey | string | - | Chart configuration parameter |
| sources.s3.existingSecretSecretKeyKey | string | - | Chart configuration parameter |
| sources.git.enabled | boolean | - | Chart configuration parameter |
| sources.git.repository | string | - | Chart configuration parameter |
| sources.git.branch | string | - | Chart configuration parameter |
| sources.git.path | string | - | Chart configuration parameter |
| sources.git.token | string | - | Chart configuration parameter |
| sources.git.existingSecret | string | - | Chart configuration parameter |
| sources.git.existingSecretTokenKey | string | - | Chart configuration parameter |
Extra Pip Packages(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraPipPackages | array | - | Extra pip packages to install at startup |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | string | - | Optional Service IP family policy Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Optional Service IP families |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Gateway API(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | - | Chart configuration parameter |
| gatewayAPI.annotations | object | - | Chart configuration parameter |
| gatewayAPI.parentRefs | array | - | Chart configuration parameter |
| gatewayAPI.hostnames | array | - | Chart configuration parameter |
| gatewayAPI.paths | array | - | Chart configuration parameter |
Health Probes(21)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.httpGet.path | string | - | Chart configuration parameter |
| probes.startup.httpGet.port | integerstring | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.httpGet.path | string | - | Chart configuration parameter |
| probes.liveness.httpGet.port | integerstring | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.httpGet.path | string | - | Chart configuration parameter |
| probes.readiness.httpGet.port | integerstring | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | - | Chart configuration parameter |
| persistence.size | string | - | Chart configuration parameter |
| persistence.storageClass | string | - | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.existingClaim | string | - | Chart configuration parameter |
Init Sync(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| initSync.enabled | boolean | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Network Policy(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.extraEgress | array | - | Additional NetworkPolicy egress rules |
Pdb(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| pdb.enabled | boolean | - | Chart configuration parameter |
| pdb.minAvailable | integer | - | Chart configuration parameter |
Autoscaling(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| autoscaling.enabled | boolean | - | Chart configuration parameter |
| autoscaling.minReplicas | integer | - | Chart configuration parameter |
| autoscaling.maxReplicas | integer | - | Chart configuration parameter |
| autoscaling.targetCPUUtilizationPercentage | integer | - | Chart configuration parameter |
| autoscaling.targetMemoryUtilizationPercentage | integerstring | - | Chart configuration parameter |
Replica Count(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| replicaCount | integer | - | Number of replicas (ignored when autoscaling is enabled) |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| resources.requests.memory | stringnumber | - | Chart configuration parameter |
| resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| resources.limits.memory | stringnumber | - | Chart configuration parameter |
Pod Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.runAsUser | integer | - | Chart configuration parameter |
| podSecurityContext.runAsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | string | - | Chart configuration parameter |
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
| podSecurityContext.seccompProfile.localhostProfile | string | - | Chart configuration parameter |
Container Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.add | array | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.runAsUser | integer | - | Chart configuration parameter |
| securityContext.runAsGroup | integer | - | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Env(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraEnv | array | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.