Showroom Docs MCP Server

Quarkus MCP Server that indexes Red Hat product documentation and the "IA Development From Zero To Hero" workshop for OpenShift Lightspeed.

Project maintained by maximilianoPizarro Hosted on GitHub Pages — Theme by mattgraham

Configuration

English | Espanol

Prerequisites

Before configuring OLSConfig with the showroom-docs-mcp server, ensure you have:

OpenShift Lightspeed Operator installed on your cluster
An LLM provider configured (e.g. OpenShift AI with vLLM, or any compatible provider)
The showroom-docs-mcp Helm chart deployed in the openshift-lightspeed namespace

Step-by-Step Setup

Step 1: Install the MCP Server

# Add the Helm repository
helm repo add showroom-docs-mcp \
  https://maximilianopizarro.github.io/showroom-docs-mcp/

# Install in the openshift-lightspeed namespace
helm install showroom-docs-mcp showroom-docs-mcp/showroom-docs-mcp \
  --namespace openshift-lightspeed \
  --set image.pullPolicy=Always

Verify the pod is running:

oc get pods -n openshift-lightspeed -l app=showroom-docs-mcp
# Expected: 1/1 Running

oc exec -n openshift-lightspeed deploy/showroom-docs-mcp -- \
  curl -s http://localhost:8080/q/health/ready
# Expected: {"status":"UP","checks":[]}

Step 2: Create LLM Credentials Secret

If you don’t already have one, create the credentials secret for your LLM provider:

oc create secret generic ols-llm-credentials \
  -n openshift-lightspeed \
  --from-literal=apitoken=<your-api-token>

For OpenShift AI with vLLM (self-hosted models), the token can be any non-empty string since authentication is handled internally.

Step 3: Enable the MCPServer Feature Gate

The MCPServer feature gate must be enabled in the OLSConfig spec:

spec:
  featureGates:
    - MCPServer

Step 4: Configure MCP Servers

Add the showroom-docs-mcp server to the mcpServers section:

  mcpServers:
    - name: showroom-docs-mcp
      timeout: 10
      url: 'http://showroom-docs-mcp.openshift-lightspeed.svc.cluster.local:8080/mcp'

Important: Use /mcp (Streamable HTTP), not /mcp/sse. The OLS client uses POST requests which require the Streamable HTTP endpoint. Using /mcp/sse will result in a 405 Method Not Allowed error.

Step 5: Apply the Complete OLSConfig

Save the following as cluster-ols.yml (also available in the repo at k8s/cluster-ols.yml):

apiVersion: ols.openshift.io/v1alpha1
kind: OLSConfig
metadata:
  name: cluster
spec:
  featureGates:
    - MCPServer
  llm:
    providers:
      - credentialsSecretRef:
          name: ols-llm-credentials
        models:
          - name: llama-32-3b-instruct
            parameters:
              maxTokensForResponse: 8192
        name: red_hat_openshift_ai
        type: rhoai_vllm
        url: 'http://llama-32-3b-instruct-openai.my-first-model.svc.cluster.local/v1'
  mcpServers:
    - name: showroom-docs-mcp
      timeout: 10
      url: 'http://showroom-docs-mcp.openshift-lightspeed.svc.cluster.local:8080/mcp'
  ols:
    conversationCache:
      postgres:
        maxConnections: 2000
        sharedBuffers: 256MB
      type: postgres
    defaultModel: llama-32-3b-instruct
    defaultProvider: red_hat_openshift_ai
    deployment:
      api:
        replicas: 1
      console:
        replicas: 1
      dataCollector: {}
      database:
        replicas: 1
      llamaStack: {}
      mcpServer: {}
    logLevel: INFO
    userDataCollection: {}
  olsDataCollector:
    logLevel: INFO

Apply it:

oc apply -f cluster-ols.yml

The OLS operator will automatically restart the lightspeed-app-server pod with the new configuration.

Step 6: Verify the Integration

Wait for the new OLS pod to be ready:

oc get pods -n openshift-lightspeed -l app.kubernetes.io/name=lightspeed-service-api -w

Check that OLS successfully loads tools from the MCP server:

oc logs -n openshift-lightspeed deploy/lightspeed-app-server \
  -c lightspeed-service-api | grep "tools from MCP"

Expected output:

Loaded 4 tools from MCP server 'showroom-docs-mcp'

If you see Failed to get tools from MCP server 'showroom-docs-mcp', check:

Error	Cause	Fix
`405 Method Not Allowed`	URL ends with `/mcp/sse`	Change URL to `/mcp`
`Connection refused`	MCP pod not running	Check `oc get pods -l app=showroom-docs-mcp`
`NoSuchMethodError: LaunchMode.isProduction()`	Quarkus version mismatch	Ensure Quarkus 3.27.3+ in pom.xml

Step 7: Test in Lightspeed Console

Open the OpenShift web console and click the Lightspeed chat icon. Try these questions:

Red Hat Product Documentation:

“How do I install OpenShift Service Mesh 3.3?”
“Explain the architecture of Red Hat Developer Hub”
“What are the steps to deploy a model with OpenShift AI?”
“How do I configure Connectivity Link gateway policies?”
“How do I set up OpenTelemetry collectors?”
“How does OpenShift Lightspeed OLSConfig work?”
“How do I create a Tekton pipeline with Pipelines as Code?”

Neuralbank Workshop:

“What is the Neuralbank workshop about?”
“How do I build an MCP agent with Quarkus?”
“What is RAG and how does it work with vector databases?”

OLSConfig Field Reference

Field	Description
`spec.featureGates`	List of feature gates to enable. `MCPServer` is required for MCP integration
`spec.llm.providers`	LLM provider configuration (model name, type, URL, credentials)
`spec.mcpServers`	List of MCP servers with name, timeout (seconds), and URL
`spec.ols.conversationCache`	Conversation history storage (postgres recommended)
`spec.ols.defaultModel`	Default LLM model name to use
`spec.ols.defaultProvider`	Default LLM provider name
`spec.ols.deployment`	Replica counts for OLS components
`spec.ols.logLevel`	Log verbosity (DEBUG, INFO, WARNING, ERROR)

MCP Server Application Configuration

application.properties

quarkus.http.port=8080
quarkus.http.host=0.0.0.0
quarkus.log.level=INFO
quarkus.log.category."com.neuralbank".level=DEBUG

Environment Variables

Variable	Default	Description
`QUARKUS_HTTP_PORT`	`8080`	Server port
`QUARKUS_LOG_LEVEL`	`INFO`	Log level
`JAVA_OPTS_APPEND`	`-Dquarkus.http.host=0.0.0.0`	Additional JVM options

Helm Chart Values

The chart includes a values.schema.json for input validation. Full parameters:

Parameter	Type	Default	Description
`replicaCount`	int	`1`	Number of replicas
`image.repository`	string	`quay.io/maximilianopizarro/showroom-docs-mcp`	Container image
`image.tag`	string	`latest`	Image tag
`image.pullPolicy`	string	`Always`	Pull policy (`Always`, `IfNotPresent`, `Never`)
`nameOverride`	string	`""`	Override chart name
`fullnameOverride`	string	`""`	Override full release name
`namespace`	string	`openshift-lightspeed`	Target namespace
`service.type`	string	`ClusterIP`	Service type (`ClusterIP`, `NodePort`, `LoadBalancer`)
`service.port`	int	`8080`	Service port
`resources.requests.cpu`	string	`100m`	CPU request
`resources.requests.memory`	string	`256Mi`	Memory request
`resources.limits.cpu`	string	`500m`	CPU limit
`resources.limits.memory`	string	`512Mi`	Memory limit
`readinessProbe.httpGet.path`	string	`/q/health/ready`	Readiness probe path
`readinessProbe.initialDelaySeconds`	int	`5`	Readiness probe initial delay
`livenessProbe.httpGet.path`	string	`/q/health/live`	Liveness probe path
`livenessProbe.initialDelaySeconds`	int	`10`	Liveness probe initial delay
`nodeSelector`	object	`{}`	Node selector constraints
`tolerations`	list	`[]`	Pod tolerations
`affinity`	object	`{}`	Pod affinity rules
`olsConfig.enabled`	bool	`false`	Enable OLSConfig integration
`olsConfig.mcpServerName`	string	`showroom-docs-mcp`	MCP server name
`olsConfig.mcpServerTimeout`	int	`10`	MCP timeout (seconds)

Example with custom values:

replicaCount: 2

image:
  repository: quay.io/maximilianopizarro/showroom-docs-mcp
  tag: latest
  pullPolicy: Always

service:
  type: ClusterIP
  port: 8080

resources:
  requests:
    cpu: 200m
    memory: 512Mi
  limits:
    cpu: 1
    memory: 1Gi

namespace: openshift-lightspeed

RAG Option (BYO Knowledge)

If you prefer native RAG instead of MCP, use the markdown files in rag-content/:

podman run -it --rm --device=/dev/fuse \
  -v $XDG_RUNTIME_DIR/containers/auth.json:/run/user/0/containers/auth.json:Z \
  -v $(pwd)/rag-content:/markdown:Z \
  -v /tmp/rag-output:/output:Z \
  registry.redhat.io/openshift-lightspeed-tech-preview/lightspeed-rag-tool-rhel9:latest

Then add the RAG image to OLSConfig:

spec:
  ols:
    rag:
      - image: image-registry.openshift-image-registry.svc:5000/openshift-lightspeed/showroom-docs-rag:latest
        indexID: showroom_docs_index
        indexPath: /rag/vector_db

Reference: Bring your own knowledge to OpenShift Lightspeed