Installation
IBM Verify MCP Server — Installation Guide
Overview
This guide walks you through deploying the IBM Verify MCP Server. Two deployment methods are supported:
| Method | Best for |
|---|---|
| Option A — Kubernetes | Production environments (single-pod; horizontal scaling is not yet supported) |
| Option B — Local Docker | Testing and evaluation |
🚀 Quick start: For a quick evaluation of the server, see Option B: Local Docker Deployment. Switch to Option A when you are ready for production.
Prerequisites
Before proceeding, ensure you have completed the Tenant Setup Prerequisites and have:
- ✅ IBM Verify tenant configured with MCP Server applications
- ✅ Client IDs and secrets for the Subject, STS, and Actor applications — see Tenant Setup
- ✅ Users entitled to the "MCP Server Subject" application
- ✅ Docker or Kubernetes environment ready
- ✅ Nginx setup if deploying on a VM or Fyre environment
Step 1: Pull the Docker Image
The IBM Verify MCP Server is distributed as a Docker image from IBM Container Registry.
Image details:
- Registry:
icr.io/ibm-verify - Image:
verify-mcp-server - Tag:
latest - Full reference:
icr.io/ibm-verify/verify-mcp-server:latest
docker pull icr.io/ibm-verify/verify-mcp-server:latest
# Verify the pull succeeded
docker images | grep verify-mcp-serverExpected output:
icr.io/ibm-verify/verify-mcp-server latest <image-id> <size> <time>Step 2: Create deployment configuration file
config.yaml is the single source of truth for all server configuration. Every string value is processed before the server starts — values that begin with a recognized prefix are resolved from their source at startup; values with no prefix are used as-is.
Supported value prefixes
| Prefix | Syntax | What it does | Requires |
|---|---|---|---|
| (none) | key: my-value | Used as-is | — |
!envvar | !envvar VAR_NAME | Reads from the named environment variable | — |
!base64 | !base64 <encoded> | Base64-decodes the payload | — |
!file | !file /path/to/file | Reads entire contents of a file | File accessible inside the container |
!enc | !enc <base64-ciphertext> | RSA/PKCS#1-v1.5 decryption | ENC_KEY env var |
!obf | !obf <base64-ciphertext> | AES-256-CBC decryption | secrets.obf_key in config.yaml |
!secret | !secret <secret-name>/<field> | Reads a field from a Kubernetes Secret | K8s cluster + RBAC |
!configmap | !configmap <configmap-name>/<field> | Reads a field from a Kubernetes ConfigMap | K8s cluster + RBAC |
!base64 is encoding, not encryption. Do not use it to protect secrets in production — use !enc or !obf instead.
You can mix prefixes freely within a single file.
Using
!encor!obffor secrets: These prefixes encrypt credentials at rest insideconfig.yamland are recommended for production.!encrequires an RSA key pair;!obfrequires a shared passphrase. See Encryption & Obfuscation for step-by-step instructions on generating encrypted values and supplying the keys.
config.yaml template
config.yaml templateThe following template uses !secret and !configmap — the recommended model for Kubernetes. Templates for other deployment methods (Docker, .env file) are provided in the relevant deployment sections.
# IBM Verify OAuth MCP Server — Configuration File
#
# Every string value supports a normalization prefix that controls how it is
# resolved at startup. Mix and match freely within this file.
#
# PREFIX REFERENCE:
# plain value — used as-is (safe for non-sensitive config)
# !envvar VAR_NAME — reads from environment variable VAR_NAME
# !base64 <encoded> — base64-decodes the payload inline
# !file /path/to/file — reads the entire contents of a file
# !enc <base64-ciphertext> — RSA decryption; requires ENC_KEY env var
# ⚠ Only needed when using !enc-prefixed values.
# See: Encryption & Obfuscation guide.
# !obf <base64-ciphertext> — AES-256-CBC decryption; requires secrets.obf_key
# ⚠ Only needed when using !obf-prefixed values.
# See: Encryption & Obfuscation guide.
# !secret <name>/<field> — reads from a Kubernetes Secret (K8s only)
# !configmap <name>/<field> — reads from a Kubernetes ConfigMap (K8s only)
#
# Default location: config.yaml in the working directory.
# ---------------------------------------------------------------------------
# Secrets
# Only required when using !obf-prefixed values. obf_key is the passphrase
# used to decrypt them. Remove this entire section if you are not using !obf.
# ---------------------------------------------------------------------------
secrets:
obf_key: !secret verify-mcp-credentials/obf_key
# ---------------------------------------------------------------------------
# Server — network binding and optional SSL/TLS (streamable-http only).
# ---------------------------------------------------------------------------
server:
host: 0.0.0.0 # Listen on all interfaces
port: 8000 # Use 8443 when use_ssl is "true"
# SSL/TLS configuration for HTTPS (streamable-http only).
# Set use_ssl to "true" to start the server with TLS on the provided port
# (use port 8443 when SSL is enabled; keep 8000 for plain HTTP).
# Examples: "false" | "true" | !envvar IBM_VERIFY_USE_SSL
use_ssl: "false"
# Path to SSL certificate PEM file (required when use_ssl is "true")
# Examples: "/app/certs/server.crt" | !envvar IBM_VERIFY_SSL_CERTFILE
ssl_certfile: ""
# Path to SSL private key PEM file (required when use_ssl is "true")
# Examples: "/app/certs/server.key" | !envvar IBM_VERIFY_SSL_KEYFILE
ssl_keyfile: ""
# Optional passphrase for encrypted private key
# Examples: "secretpass" | !envvar IBM_VERIFY_SSL_KEYFILE_PASSWORD
ssl_keyfile_password: ""
# Optional path to CA bundle / certificate chain file (leave commented out unless using custom CA/mTLS)
# Examples: "/app/certs/ca-bundle.crt" | !envvar IBM_VERIFY_SSL_CA_CERTS
# ssl_ca_certs: ""
# ---------------------------------------------------------------------------
# IBM Verify — OAuth credentials and endpoint configuration.
#
# Required fields:
# tenant_url, client_id, client_secret, base_url,
# sts_client_id, sts_client_secret, actor_client_id, actor_client_secret
#
# Optional fields are auto-constructed from tenant_url if omitted.
# ---------------------------------------------------------------------------
ibm_verify:
# IBM Verify tenant base URL
# Example: https://my-tenant.verify.ibm.com
tenant_url: !configmap verify-mcp-config/IBM_VERIFY_TENANT_URL
# tenant_url: https://my-tenant.verify.ibm.com # plain text alternative
# Subject application OAuth credentials
client_id: !secret verify-mcp-credentials/client-id
# client_id: my-subject-client-id # plain text example
client_secret: !secret verify-mcp-credentials/client-secret
# client_secret: my-subject-client-secret # plain text; use !enc or !obf in production
# Public URL of this MCP server — used as the OAuth redirect base.
# Use http://localhost:8000 for local testing.
# Use your public HTTPS hostname for production deployments.
base_url: https://mcp-server.example.com
# STS client for token exchange
sts_client_id: !secret verify-mcp-credentials/sts-client-id
# sts_client_id: my-sts-client-id # plain text example
sts_client_secret: !secret verify-mcp-credentials/sts-client-secret
# sts_client_secret: my-sts-client-secret # plain text; use !enc or !obf in production
# Actor client for enhanced audit logging
actor_client_id: !secret verify-mcp-credentials/actor-client-id
# actor_client_id: my-actor-client-id # plain text example
actor_client_secret: !secret verify-mcp-credentials/actor-client-secret
# actor_client_secret: my-actor-client-secret # plain text; use !enc or !obf in production
# Recommended for production: restrict allowed OAuth redirect URIs.
# If unset, any redirect URI is accepted — open-redirect risk.
# allowed_redirect_uris: https://client.mycompany.com/callback
# Optional — auto-constructed from tenant_url if omitted
# oidc_config_url: https://...
# token_exchange_url: https://...
# introspection_url: https://...
scopes: openid profile email
# ---------------------------------------------------------------------------
# Transport
# The only accepted value is streamable-http.
# ---------------------------------------------------------------------------
transport:
type: streamable-http
# authentication_method: oidc_proxy # default; change to direct_token if needed
# ---------------------------------------------------------------------------
# Cache — token cache (streamable-http only).
# ---------------------------------------------------------------------------
cache:
ttl: 900 # seconds
maxsize: 1000 # max cached tokens
# ---------------------------------------------------------------------------
# Logging
# ---------------------------------------------------------------------------
logging:
level: INFO # DEBUG | INFO | WARNING | ERROR | CRITICAL
# Log file inside the container.
file: /app/logs/mcp-server.log
max_bytes: 10485760 # 10 MB per file
backup_count: 5config.yaml Configuration Reference
config.yaml Configuration ReferenceAll the supported configuration parameters are listed as follows. Required parameters must be present or the server doesn't start.
secrets section
secrets section| Parameter | Type | Required | Description |
|---|---|---|---|
secrets.obf_key | string | Only if using !obf values | Passphrase used to decrypt !obf-prefixed values (AES-256-CBC/PBKDF2-SHA512). Never store in plain text — supply through !envvar or !secret. |
secrets:
obf_key: !envvar OBF_KEYserver section
server section| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
server.host | string | ✅ Yes | 0.0.0.0 | Network interface the server listens on. |
server.port | integer | ✅ Yes | 8000 | TCP port on which the server accepts incoming connections. Use 8000 for HTTP (default) and 8443 when server.use_ssl is "true". |
server.use_ssl | string | No | "false" | Set to "true" to start the server with HTTPS/TLS on server.port (streamable-http only). Example: "true" or !envvar IBM_VERIFY_USE_SSL. |
server.ssl_certfile | string | Only if server.use_ssl is "true" | — | Path to the SSL certificate PEM file inside the container. Example: /app/certs/server.crt or !envvar IBM_VERIFY_SSL_CERTFILE. |
server.ssl_keyfile | string | Only if server.use_ssl is "true" | — | Path to the SSL private key PEM file inside the container. Example: /app/certs/server.key or !envvar IBM_VERIFY_SSL_KEYFILE. |
server.ssl_keyfile_password | string | No | — | Passphrase for an encrypted private key. Example: !envvar IBM_VERIFY_SSL_KEYFILE_PASSWORD. Do not store as plain text in production. |
server.ssl_ca_certs | string | No | — | Path to a CA bundle / certificate chain file. Only needed for a custom CA or mutual TLS (mTLS). Example: /app/certs/ca-bundle.crt or !envvar IBM_VERIFY_SSL_CA_CERTS. |
To generate the certificate and private key that server.ssl_certfile and server.ssl_keyfile point to, see SSL/TLS Certificate Generation in the Encryption & Obfuscation guide.
To run the server in SSL mode (port 8443), see Enable SSL/TLS (optional) in the Kubernetes section or Enable SSL/TLS (optional) in the Docker section.
ibm_verify section
ibm_verify section| Parameter | Type | Required | Description |
|---|---|---|---|
ibm_verify.tenant_url | string | ✅ Yes | IBM Verify tenant base URL. Example: https://mytenant.verify.ibm.com |
ibm_verify.client_id | string | ✅ Yes | OAuth client ID for the Subject application. |
ibm_verify.client_secret | string | ✅ Yes | OAuth client secret. Use !enc or !obf in production. |
ibm_verify.base_url | string | ✅ Yes | Public URL of this MCP server, used as the OAuth redirect base (streamable-http only). |
ibm_verify.sts_client_id | string | ✅ Yes | Client ID for the STS application (token exchange). |
ibm_verify.sts_client_secret | string | ✅ Yes | Client secret for the STS application. Use !enc or !obf in production. |
ibm_verify.actor_client_id | string | ✅ Yes | Client ID for the Actor application (audit logging). |
ibm_verify.actor_client_secret | string | ✅ Yes | Client secret for the Actor application. Use !enc or !obf in production. |
ibm_verify.oidc_config_url | string | No | OIDC discovery document URL. Auto-constructed from tenant_url if omitted. |
ibm_verify.token_exchange_url | string | No | Token exchange endpoint URL. Auto-constructed from tenant_url if omitted. |
ibm_verify.introspection_url | string | No | Token introspection endpoint URL. Auto-constructed from tenant_url if omitted. |
ibm_verify.scopes | string | No | Space-separated OAuth scopes. Default: openid profile email |
ibm_verify.allowed_redirect_uris | string | No | Comma-separated list of allowed OAuth redirect URIs. Always set this in production to prevent open-redirect attacks. |
transport section
transport section| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
transport.type | string | ✅ Yes | streamable-http | Transport protocol. Only accepted value: streamable-http. |
transport.authentication_method | string | No | oidc_proxy | Authentication method for streamable-http. Accepted values: oidc_proxy, direct_token. |
cache section (streamable-http only)
cache section (streamable-http only)| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
cache.ttl | integer | No | 900 | Token cache time-to-live in seconds. |
cache.maxsize | integer | No | 1000 | Maximum number of tokens held in cache. |
logging section
logging section| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
logging.level | string | ✅ Yes | INFO | Log verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL. |
logging.file | string | No | (stderr) | Path to log file inside the container. |
logging.max_bytes | integer | No | 10485760 | Maximum log file size before rotation (bytes). Default is 10 MB. |
logging.backup_count | integer | No | 5 | Number of rotated log file backups to retain. |
Step 3: Choose Your Deployment Method
Select the path that matches your environment:
- Option A: Kubernetes Deployment — for production clusters
- Option B: Local Docker Deployment — for development and testing
Option A: Kubernetes Deployment
This is the recommended deployment model for production. Credentials are resolved directly from Kubernetes Secrets at pod startup — they are never written to environment variables or the filesystem.
How it works
- Non-sensitive configuration (tenant URL, server port, etc.) is stored in a ConfigMap, created from
config.yaml. - All secrets (client credentials, obfuscation key) are stored in a Kubernetes Secret and referenced in
config.yamlby using the!secretprefix. - If you use
!enc-encrypted values, the RSA private key is stored in a separate Kubernetes Secret and referenced throughENC_KEY.
A.1 Prerequisites
- Kubernetes (v1.19+) or OpenShift cluster
kubectl/ocCLI configured to access your cluster- Ingress controller (nginx, Traefik, etc.) or an OpenShift Route for external access
- IBM Verify tenant credentials from Tenant Setup
A.2 Create a Namespace
NAMESPACE=verify-mcp-server
kubectl create namespace "${NAMESPACE}"A.3 Create the Credentials Secret
Store all sensitive values in a Kubernetes Secret. The config.yaml template in Step 2 references these by using !secret verify-mcp-credentials/<key>.
kubectl create secret generic verify-mcp-credentials \
--namespace="${NAMESPACE}" \
--from-literal=client-id='<subject-app-client-id>' \
--from-literal=client-secret='<subject-app-client-secret>' \
--from-literal=sts-client-id='<sts-app-client-id>' \
--from-literal=sts-client-secret='<sts-app-client-secret>' \
--from-literal=actor-client-id='<actor-app-client-id>' \
--from-literal=actor-client-secret='<actor-app-client-secret>'
# Add --from-literal=obf_key='<passphrase>' only if using !obf valuesUsing encryption: You can store
!enc <ciphertext>values here instead of plain text. See Encryption & Obfuscation for instructions on generating ciphertexts.
Update config.yaml to set all client IDs and secrets to reference the secrets created above:
ibm_verify:
client_id: !secret verify-mcp-credentials/client-id
client_secret: !secret verify-mcp-credentials/client-secret
sts_client_id: !secret verify-mcp-credentials/sts-client-id
sts_client_secret: !secret verify-mcp-credentials/sts-client-secret
actor_client_id: !secret verify-mcp-credentials/actor-client-id
actor_client_secret: !secret verify-mcp-credentials/actor-client-secret
# only if using !obf values is used
secrets:
obf_key: !secret verify-mcp-credentials/obf_keyA.4 Create the RSA Private Key Secret (only if using !enc)
!enc)This step is required only when any value in your config.yaml uses the !enc prefix. The RSA private key is used to decrypt the !enc-prefixed values at startup.
kubectl create secret generic verify-mcp-enc-key \
--namespace="${NAMESPACE}" \
--from-file=private.pem=./private.pemThe deployment manifest (see Apply the Deployment Manifest) sets ENC_KEY to reference this secret:
- name: ENC_KEY
value: "!secret verify-mcp-enc-key/private.pem"Keep
private.pemout of version control. Add it to.gitignoreand use a secrets manager for production deployments. The!secretapproach means the PEM content is fetched directly from the cluster — it never touches an env var or mounted file.
A.5 Create the ConfigMap from config.yaml
config.yamlIf your
config.yamluses!configmap verify-mcp-config/<key>references (as in the template above), create that ConfigMap:kubectl create configmap verify-mcp-config \ --namespace="${NAMESPACE}" \ --from-literal=IBM_VERIFY_TENANT_URL='https://mytenant.verify.ibm.com'
Update config.yaml to set tenant_url to reference the ConfigMap previously created:
ibm_verify:
tenant_url: !configmap verify-mcp-config/IBM_VERIFY_TENANT_URLValidate config.yaml, then load it into Kubernetes as a ConfigMap so it can be mounted into the container:
kubectl create configmap verify-mcp-files \
--namespace="${NAMESPACE}" \
--from-file=config.yaml=./config.yamlA.6 Apply the Deployment Manifest
Save the following as verify-mcp-server.yaml and apply it. Update the namespace, image tag, and base_url in config.yaml before applying. Lines marked # SSL: apply only when running the server in SSL mode — see Enable SSL/TLS (optional); leave them unchanged for the default HTTP setup.
# ============================================================================
# IBM Verify MCP Server — Kubernetes manifest
# Apply with: kubectl apply -f verify-mcp-server.yaml
# ============================================================================
# ----------------------------------------------------------------------------
# 1. ServiceAccount
# A dedicated ServiceAccount instead of the default namespace SA.
# ----------------------------------------------------------------------------
apiVersion: v1
kind: ServiceAccount
metadata:
name: verify-mcp-server-sa
namespace: verify-mcp-server
---
# ----------------------------------------------------------------------------
# 2. Role
# Grants the pod permission to read Secrets and ConfigMaps.
# Required for !secret and !configmap prefix resolution.
# ----------------------------------------------------------------------------
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: verify-mcp-server-role
namespace: verify-mcp-server
rules:
- apiGroups: [""]
resources: ["secrets"]
verbs: ["get", "list"]
- apiGroups: [""]
resources: ["configmaps"]
verbs: ["get", "list"]
---
# ----------------------------------------------------------------------------
# 3. RoleBinding
# ----------------------------------------------------------------------------
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: verify-mcp-server-rolebinding
namespace: verify-mcp-server
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: verify-mcp-server-role
subjects:
- kind: ServiceAccount
name: verify-mcp-server-sa
namespace: verify-mcp-server
---
# ----------------------------------------------------------------------------
# 4. Deployment
# ----------------------------------------------------------------------------
apiVersion: apps/v1
kind: Deployment
metadata:
name: verify-mcp-server
namespace: verify-mcp-server
labels:
app: verify-mcp-server
version: v1
spec:
replicas: 1
selector:
matchLabels:
app: verify-mcp-server
template:
metadata:
labels:
app: verify-mcp-server
version: v1
annotations:
instana.io/instrumentation: "false"
spec:
# securityContext can be updated as per security requirement
securityContext: {}
serviceAccountName: verify-mcp-server-sa
containers:
- name: verify-mcp-server
image: icr.io/ibm-verify/verify-mcp-server:latest
imagePullPolicy: Always
# DO NOT override command — doing so bypasses all prefix resolution
# and the server will fail to start.
ports:
- name: http # SSL: use https
containerPort: 8000 # SSL: use 8443
protocol: TCP
env:
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
# ENC_KEY — required ONLY when config.yaml contains !enc-prefixed values.
# Points to the RSA private key used to decrypt those values.
# Using !secret here means the PEM content is fetched directly from the cluster secrets store — it never touches a mounted file or env var.
# Remove this entry entirely if you are not using !enc.
- name: ENC_KEY
value: "!secret verify-mcp-enc-key/private.pem"
resources:
requests:
memory: "512Mi"
cpu: "500m"
limits:
memory: "1Gi"
cpu: "1000m"
# Liveness probe — 30s delay allows config resolution to complete before the probe fires.
livenessProbe:
httpGet:
path: /health
port: 8000 # SSL: use 8443
# scheme: HTTPS # SSL: uncomment
initialDelaySeconds: 30
periodSeconds: 15
timeoutSeconds: 5
failureThreshold: 3
readinessProbe:
httpGet:
path: /health
port: 8000 # SSL: use 8443
# scheme: HTTPS # SSL: uncomment
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 3
failureThreshold: 3
volumeMounts:
- name: logs
mountPath: /app/logs
# config.yaml is mounted read-only from the verify-mcp-files ConfigMap.
- name: mcp-files
mountPath: /app/config/config.yaml
subPath: config.yaml
readOnly: true
# SSL: uncomment to mount the TLS Secret created in "Enable SSL/TLS (optional)" at /app/certs.
# - name: tls-certs
# mountPath: /app/certs
# readOnly: true
volumes:
- name: logs
emptyDir: {}
- name: mcp-files
configMap:
name: verify-mcp-files
# SSL: uncomment to add the TLS Secret created in "Enable SSL/TLS (optional)".
# - name: tls-certs
# secret:
# secretName: verify-mcp-tls
restartPolicy: Always
---
# ----------------------------------------------------------------------------
# 5. Service
# ----------------------------------------------------------------------------
apiVersion: v1
kind: Service
metadata:
name: verify-mcp-server
namespace: verify-mcp-server
labels:
app: verify-mcp-server
spec:
type: ClusterIP
ports:
- port: 8000 # SSL: use 8443
targetPort: 8000 # SSL: use 8443
protocol: TCP
name: http # SSL: use https
selector:
app: verify-mcp-serverkubectl apply -f verify-mcp-server.yamlExpected output:
serviceaccount/verify-mcp-server-sa is created
role.rbac.authorization.k8s.io/verify-mcp-server-role is created
rolebinding.rbac.authorization.k8s.io/verify-mcp-server-rolebinding is created
deployment.apps/verify-mcp-server is created
service/verify-mcp-server is createdA.6.1 Enable SSL/TLS (optional)
By default the server listens on plain HTTP on port 8000 and TLS is terminated at the Ingress or Route. To have the server itself serve HTTPS (for example, for end-to-end encryption), complete the following steps. When SSL is enabled, the server uses port 8443 instead of 8000.
Certificates and client trust: MCP clients must trust the certificate presented to them. They see the Route or Ingress certificate with
reencrypttermination, and the server's certificate withpassthrough. A self-signed or private-CA certificate needs the same client-side trust configuration in either case. Use a certificate from a public CA, or configure the MCP client to trust your certificate. See Self-Signed Certificates in the Configuring MCP Clients guide.
Certificate and private key: Before proceeding, ensure you have a
server.crtandserver.keyin PEM format. See SSL/TLS Certificate Generation in the Encryption & Obfuscation guide foropensslcommands to generate a self-signed certificate or a CA-signed certificate.
1. Create a TLS Secret containing the certificate, private key, and (optionally) a CA bundle:
kubectl create secret generic verify-mcp-tls \
--namespace="${NAMESPACE}" \
--from-file=server.crt=./server.crt \
--from-file=server.key=./server.key
# Optional, only for a custom CA / mTLS: --from-file=ca-bundle.crt=./ca-bundle.crtIf the private key is encrypted, add the passphrase to the credentials Secret created in Create the Credentials Secret:
kubectl patch secret verify-mcp-credentials -n "${NAMESPACE}" \
--type merge -p '{"stringData":{"ssl-keyfile-password":"<key-passphrase>"}}'2. Update the server section of config.yaml, then recreate the ConfigMap (see Kubernetes Management Commands):
server:
host: 0.0.0.0
port: 8443
use_ssl: "true"
ssl_certfile: /app/certs/server.crt
ssl_keyfile: /app/certs/server.key
# Only if the key is encrypted: reads the ssl-keyfile-password key from the
# verify-mcp-credentials Secret (the key added with the kubectl patch command above).
# ssl_keyfile_password: !secret verify-mcp-credentials/ssl-keyfile-password
# Only for custom CA / mTLS:
# ssl_ca_certs: /app/certs/ca-bundle.crt3. Update verify-mcp-server.yaml (see Apply the Deployment Manifest). Every line that changes for SSL mode is marked with # SSL: in the Deployment and Service. Apply these changes:
- Container port, Service
port/targetPort, and both probe ports:8000→8443 - Port names:
http→https - Both probes: uncomment
scheme: HTTPS volumeMountsandvolumes: uncomment thetls-certsentries, which mount theverify-mcp-tlsSecret at/app/certs
Re-apply the manifest and restart:
kubectl apply -f verify-mcp-server.yaml
kubectl rollout restart deployment verify-mcp-server -n "${NAMESPACE}"4. Update external access (see Expose through Ingress or Route) so the Ingress or Route connects to the backend over HTTPS on port 8443:
-
OpenShift Route: set
port.targetPorttohttps(the Service port name) and usereencrypt(orpassthrough) termination instead ofedge:port: targetPort: https tls: termination: reencrypt # or: passthrough insecureEdgeTerminationPolicy: Redirect # For reencrypt, provide the backend CA so the router trusts the server certificate: # destinationCACertificate: | # -----BEGIN CERTIFICATE----- # ... -
Kubernetes Ingress (nginx): add the backend protocol annotation and point the backend at port
8443:annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"port: number: 8443
5. Test:
kubectl port-forward -n "${NAMESPACE}" svc/verify-mcp-server 8443:8443
curl -k https://localhost:8443/healthSet
ibm_verify.base_urlto the public HTTPS URL of the server. If the pod fails readiness checks after enabling SSL, confirm the probes usescheme: HTTPSand check logs withkubectl logs -n "${NAMESPACE}" -l app=verify-mcp-server.
A.7 Expose through Ingress or Route
Add the appropriate resource to expose the service externally.
For OpenShift (Route):
apiVersion: route.openshift.io/v1
kind: Route
metadata:
name: verify-mcp-server
namespace: verify-mcp-server
labels:
app: verify-mcp-server
spec:
host: <external-hostname, e.g. verify-mcp-server.example.com>
to:
kind: Service
name: verify-mcp-server
weight: 100
port:
targetPort: http
tls:
termination: edge
insecureEdgeTerminationPolicy: Redirect
wildcardPolicy: NoneFor standard Kubernetes (Ingress):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: verify-mcp-server
namespace: verify-mcp-server
labels:
app: verify-mcp-server
annotations:
# Adjust for your ingress controller, e.g.:
# nginx.ingress.kubernetes.io/rewrite-target: /
spec:
ingressClassName: nginx
rules:
- host: <external-hostname, e.g. verify-mcp-server.example.com>
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: verify-mcp-server
port:
number: 8000A.8 Verify the Deployment
# Check all resources in the namespace
kubectl get all -n "${NAMESPACE}"
# Check configmaps and secrets
kubectl get configmap,secret -n "${NAMESPACE}"Expected output:
NAME READY STATUS RESTARTS AGE
pod/verify-mcp-server-xxxxxxxxxx-xxxxx 1/1 Running 0 30s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/verify-mcp-server ClusterIP 10.96.xxx.xxx <none> 8000/TCP 30s
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/verify-mcp-server 1/1 1 1 30s
NAME DATA AGE
configmap/verify-mcp-config 1 30s
configmap/verify-mcp-files 1 30s
NAME TYPE DATA AGE
secret/verify-mcp-credentials Opaque 6 30s
secret/verify-mcp-enc-key Opaque 1 30sA.9 Test the Deployment
# Port-forward to test locally
kubectl port-forward -n "${NAMESPACE}" svc/verify-mcp-server 8000:8000
# In a separate terminal
curl http://localhost:8000/healthExpected response:
{
"status": "healthy",
"service": "IBM Verify MCP Server"
}If the health check fails, inspect logs:
kubectl logs -n "${NAMESPACE}" -l app=verify-mcp-server --tail=50. Common causes are missing or misconfigured secrets, or an unreachable IBM Verify tenant. See the Troubleshooting Guide.
A.10 Kubernetes Management Commands
View logs:
# Follow logs
kubectl logs -f -n "${NAMESPACE}" -l app=verify-mcp-server
# View last 100 lines
kubectl logs -n "${NAMESPACE}" -l app=verify-mcp-server --tail=100Update configuration:
# Recreate the ConfigMap from an updated config.yaml:
kubectl create configmap verify-mcp-files \
--namespace="${NAMESPACE}" \
--from-file=config.yaml=./config.yaml \
--dry-run=client -o yaml | kubectl apply -f -
# Restart the deployment to pick up changes:
kubectl rollout restart deployment verify-mcp-server -n "${NAMESPACE}"Update image:
# Update the image tag in verify-mcp-server.yaml, then re-apply:
kubectl apply -f verify-mcp-server.yaml
# Or update in-place:
kubectl set image deployment/verify-mcp-server \
verify-mcp-server=icr.io/ibm-verify/verify-mcp-server:latest \
-n "${NAMESPACE}"
kubectl rollout status deployment verify-mcp-server -n "${NAMESPACE}"Scale:
# Only single-pod deployment is currently supported.
# Do not scale above 1 — session/cache state is in-process and not shared
# across pods. HA support is planned for a future release.
kubectl scale deployment verify-mcp-server -n "${NAMESPACE}" --replicas=1Delete deployment:
kubectl delete namespace "${NAMESPACE}"Option B: Local Docker Deployment
Run the MCP Server locally for testing or evaluation.
Prerequisites
- Docker installed and running
- Access to IBM Container Registry (
icr.io) config.yamlcreated in Step 2
B.1 Prepare the Working Directory
mkdir -p ./config ./logs
cp /path/to/config.yaml ./config/config.yaml./
├── config/
│ └── config.yaml ← required
└── logs/ ← mount to persist logsIf you are using
!enc-prefixed values, also create asecrets/folder and place yourprivate.peminside it.
A minimal config.yaml for Docker to reference credentials:
# config.yaml for Docker / local deployment
# Either we can edit this file directly or make Uses !envvar so credentials are loaded from the .env file or -e flags at runtime.
# Credentials can be set as plain text, or resolved at runtime using !envvar, !enc, or !obf prefixes.
secrets:
obf_key: !envvar OBF_KEY # Needed only when using !obf-prefixed values; supply the passphrase through an environment variable
server:
host: 0.0.0.0
port: 8000
ibm_verify:
tenant_url: https://<my-tenant.verify.ibm.com>
client_id: <your-subject-client-id> # For production: !enc <base64-ciphertext>
client_secret: <your-subject-client-secret> # For production: !enc <base64-ciphertext>
base_url: https://<mcp-server.example.com>
sts_client_id: <your-sts-client-id> # For production: !enc <base64-ciphertext>
sts_client_secret: <your-sts-client-secret> # For production: !enc <base64-ciphertext>
actor_client_id: <your-actor-client-id> # For production: !enc <base64-ciphertext>
actor_client_secret: <your-actor-client-secret> # For production: !enc <base64-ciphertext>
scopes: openid profile email
transport:
type: streamable-http
logging:
level: INFO
file: /app/logs/mcp-server.logB.2 Run the Container
Apple Silicon / non-amd64 hosts: Add
--platform linux/amd64immediately afterdocker run.
Run the following command, including the optional flags that match how your config.yaml is configured:
docker run -d \
--name verify-mcp-server \
-p 8000:8000 \
-v "$(pwd)/config:/app/config:ro" \
-v "$(pwd)/logs:/app/logs" \
# [Optional: Only if using !enc (RSA encryption)] Mount private key and set ENC_KEY
# -v "$(pwd)/secrets:/app/secrets:ro" \
# -e ENC_KEY="!file /app/secrets/private.pem" \
# [Optional: Only if using !envvar in config.yaml] Load environment variables
# --env-file .env \
--restart unless-stopped \
icr.io/ibm-verify/verify-mcp-server:latestAdditional parameters by configuration type
-
When using
!enc(RSA encryption):
Mount your private key directory and pointENC_KEYat the file path inside the container:-v "$(pwd)/secrets:/app/secrets:ro" \ -e ENC_KEY="!file /app/secrets/private.pem"(Note: The path in
ENC_KEYmust match the mount path inside the container). -
When using
!obf(Obfuscation):
Provide the passphrase throughsecrets.obf_keyinconfig.yaml. Never store the passphrase as plain text inconfig.yaml— supply it at runtime through an environment variable or a mounted file:secrets: # obf_key: MyMasterPassword # ⚠️ INSECURE — plain text in config file; do not use in production obf_key: !envvar OBF_KEY # recommended: read from environment variable # obf_key: !file /app/secrets/obf # alternative: read from a mounted file -
When using
!envvar:
Pass variables using--env-file .envor individual-e KEY="value"flags. -
When running in SSL/TLS mode (
server.use_ssl: "true"):
See Enable SSL/TLS (optional).
B.2.1 Enable SSL/TLS (optional)
The server can serve HTTPS directly (streamable-http only), so a reverse proxy is optional. When SSL is enabled, use port 8443 instead of the default 8000.
Certificates and client trust: MCP clients must trust the certificate that the server (or a reverse proxy in front of it) presents. A reverse proxy does not change this — a self-signed or private-CA certificate on nginx has the same trust requirement as one on the server itself. Use a certificate from a public CA, or configure the MCP client to trust your certificate. See Self-Signed Certificates in the Configuring MCP Clients guide. Use a reverse proxy only if you need it for other reasons, such as a standard port 443, shared hostnames, or centralized certificate management.
Certificate and private key: Before proceeding, ensure you have a
server.crtandserver.keyin PEM format. See SSL/TLS Certificate Generation in the Encryption & Obfuscation guide foropensslcommands to generate a self-signed certificate or a CA-signed certificate.
-
Place your certificate and private key (PEM format) in a local
certs/folder:mkdir -p ./certs cp /path/to/server.crt ./certs/server.crt cp /path/to/server.key ./certs/server.key # Optional, only for a custom CA / mTLS: # cp /path/to/ca-bundle.crt ./certs/ca-bundle.crt./ ├── config/ │ └── config.yaml ├── certs/ ← SSL certificate, key, and optional CA bundle └── logs/Use
./certs/as the persistent location for the certificate files. After your CA signs the certificate, copy the signedserver.crt(andca-bundle.crtif required) here, alongside the originalserver.key, which must match the signed certificate. Because the folder is mounted into the container, it survives container re-creation. When you renew the certificate, replace the files in this folder and restart the container. -
Update the
serversection ofconfig.yaml. The paths are paths inside the container:server: host: 0.0.0.0 port: 8443 use_ssl: "true" ssl_certfile: /app/certs/server.crt ssl_keyfile: /app/certs/server.key # ssl_keyfile_password: !envvar IBM_VERIFY_SSL_KEYFILE_PASSWORD # only if the key is encrypted # ssl_ca_certs: /app/certs/ca-bundle.crt # only for custom CA / mTLSAlso set
ibm_verify.base_urlto anhttps://URL (for example,https://localhost:8443). -
Mount the
certsfolder when you run the container. If the private key is encrypted, also pass the passphrase:docker run -d \ --name verify-mcp-server \ -p 8443:8443 \ -v "$(pwd)/config:/app/config:ro" \ -v "$(pwd)/logs:/app/logs" \ -v "$(pwd)/certs:/app/certs:ro" \ # [Optional: Only if the private key is encrypted] # -e IBM_VERIFY_SSL_KEYFILE_PASSWORD='<key-passphrase>' \ --restart unless-stopped \ icr.io/ibm-verify/verify-mcp-server:latest -
Verify with HTTPS:
curl -k https://localhost:8443/health
Notes:
- The key file must be readable by the container user. If the server fails to start, check
docker logs verify-mcp-serverfor certificate or key errors.- Remember that
ssl_*values can also be supplied through!envvar, for examplessl_certfile: !envvar IBM_VERIFY_SSL_CERTFILE.- Do not store
ssl_keyfile_passwordas plain text inconfig.yaml; use!envvar,!enc, or!obf.
B.3 Confirm the Container is Running
docker ps | grep verify-mcp-server
docker logs verify-mcp-server --tail=30B.4 Container Management
docker logs -f verify-mcp-server # follow live logs
docker logs verify-mcp-server --tail=50 # view last 50 lines
docker stop verify-mcp-server
docker start verify-mcp-server
docker restart verify-mcp-server
docker rm -f verify-mcp-serverValidate the Installation
Regardless of deployment method, confirm the server is running correctly before proceeding.
Health Check
# Docker
curl http://localhost:8000/health
# Kubernetes (through port-forward)
kubectl port-forward -n "${NAMESPACE}" svc/verify-mcp-server 8000:8000
curl http://localhost:8000/health
# Kubernetes (through ingress hostname)
curl https://mcp.mycompany.com/healthIf SSL is enabled (server.use_ssl: "true"), use https instead. Add -k for self-signed certificates, or --cacert <ca-file> to validate against your CA:
# Docker (SSL mode)
curl -k https://localhost:8443/health
# Kubernetes (SSL mode, through port-forward)
kubectl port-forward -n "${NAMESPACE}" svc/verify-mcp-server 8443:8443
curl -k https://localhost:8443/healthExpected response:
{
"status": "healthy",
"service": "IBM Verify MCP Server"
}Verify Server Logs
# Docker
docker logs verify-mcp-server --tail=50
# Kubernetes
kubectl logs -n "${NAMESPACE}" -l app=verify-mcp-server --tail=50Look for:
- ✅ Server started successfully
- ✅ No error messages
- ✅ Listening on port 8000 (or 8443 when SSL is enabled)
Post-Installation: Nginx Reverse Proxy (VM / Fyre)
When deploying on a VM or Fyre environment with SSL disabled, the server runs on plain HTTP (port 8000). Because MCP clients require HTTPS, place an nginx reverse proxy in front of it. This is not needed if you enable SSL on the server itself (port 8443).
- nginx terminates HTTPS on port 443 (or a custom port such as 2443)
- nginx proxies requests to
http://localhost:8000
Self-signed certificates: In Fyre or lab environments you can generate a self-signed TLS certificate. MCP clients must be configured to trust it. See the Configuring MCP Clients guide for self-signed certificate setup instructions.
For nginx setup instructions, refer to the nginx reverse proxy guide or the DigitalOcean nginx reverse proxy tutorial.
Resource and Network Requirements
Compute (per pod / container):
| CPU | Memory | |
|---|---|---|
| Minimum | 500m (0.5 cores) | 512 Mi |
| Recommended | 1000m (1 core) | 1 Gi |
Network:
| Direction | Port | Protocol | Purpose |
|---|---|---|---|
| Inbound | 8000 | HTTP | MCP Server API (default, server.use_ssl: "false") |
| Inbound | 8443 | HTTPS | MCP Server API (when server.use_ssl is "true") |
| Outbound | 443 | HTTPS | IBM Verify tenant communication |
Troubleshooting
For a full list of issues and solutions, see the Troubleshooting Guide.
Quick debug commands:
# Docker — check logs
docker logs verify-mcp-serverNext Steps
Once the server is running:
- 👉 Configure MCP Clients — Connect Claude Desktop, IBM Bob, or other MCP-compatible clients
- ✅ Test the authentication flow end-to-end with an entitled user
- ✅ Review Encryption & Obfuscation to harden credentials for production
- ✅ Set
allowed_redirect_urisinconfig.yamlto lock down OAuth redirect targets - ✅ Set up monitoring, log retention, and alerting
Additional Resources
- Encryption & Obfuscation — Generate
!obfand!encvalues for use inconfig.yaml - Tenant Setup Prerequisites — IBM Verify application configuration
- Troubleshooting Guide
- IBM Verify Documentation
- Kubernetes Documentation
- Docker Documentation
- MCP Protocol Specification
Support
For issues or questions:
- Review the Troubleshooting Guide
- Consult IBM Verify support documentation
- Contact your IBM Verify administrator
Updated 14 days ago
