Architecture

MCP protocol overview

Model Context Protocol (MCP) is an open standard for connecting AI agents to tools and data sources. It defines a JSON-RPC 2.0 protocol for tool discovery (tools/list), invocation (tools/call), resource access, and prompt templates.

MCP is not tied to any vendor or platform. It works across AI hosts (OpenCode, Cursor, Claude, VS Code, and others) and runtimes (containers, serverless, local processes).

┌───────────────────────────────────────────┐
│  HOST (OpenCode)                          │
│   ┌──────────┐         ┌──────────┐       │
│   │ AI Model │◄───────►│ MCP      │       │
│   │ (LLM)    │ JSON-RPC│ Client   │       │
│   └──────────┘         └────┬─────┘       │
└─────────────────────────────┼─────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   MCP SERVER      │
                    │   (your code)     │
                    │                   │
                    │  Tool: get_stock  │
                    │  Tool: get_news   │
                    │  Data: Yahoo API  │
                    └───────────────────┘

Three layers:

  • Host — the application running the AI (OpenCode in this workshop)

  • Client — built into the host; discovers tools, routes calls, returns results

  • Server — YOUR code; defines tools and connects to external data

MCP server lifecycle on OpenShift

Deploying an MCP server on OpenShift involves three layers:

Layer Component What it does

Deploy

MCP Lifecycle Operator

Watches MCPServer CRs, auto-creates Deployment + Service + NetworkPolicy, performs MCP handshake verification

Discover

AI Hub MCP Catalog

Dashboard UI where deployed MCPServer CRs appear for browsing and management

Route & Govern

MCP Gateway (RHCL)

Single entry point for all MCP servers; federated tool discovery, auth, rate limiting via HTTPRoute + MCPServerRegistration

Layer 1: Deploy (MCPServer CR)

Instead of manually creating Deployments, Services, and security config, you create a single MCPServer custom resource:

apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: user1-stock-mcp
spec:
  source:
    type: ContainerImage
    containerImage:
      ref: image-registry.../user1-stock-mcp@sha256:...
  config:
    port: 8080
    path: /mcp

The MCP Lifecycle Operator automatically:

  • Creates a security-hardened Deployment (non-root, drop ALL caps, read-only FS, seccomp)

  • Creates a Service (ClusterIP) for internal access

  • Creates a NetworkPolicy for network segmentation

  • Performs an MCP protocol handshake to verify the server responds correctly

Layer 2: Discover (AI Hub)

Deployed MCPServer CRs appear on the OpenShift AI dashboard under AI Hub → MCP servers → Deployments. Pre-built servers from Red Hat, partners, and the community are also available for one-click deployment.

Layer 3: Route & Govern (MCP Gateway)

The MCP Gateway provides a single, governed entry point. You register your server with:

  • An HTTPRoute — maps your server’s path on the gateway

  • An MCPServerRegistration — tells the gateway your tools and adds a prefix to avoid collisions (e.g., user1_stock_get_price)

Inference path

The workshop uses a private LLM served by llm-d + vLLM on the same cluster. The inference path:

OpenCode → MaaS Gateway (API key auth) → llm-d → vLLM (GPU)

MCP tool calls go directly from the OpenCode MCP client to your MCPServer pod — they do not pass through the LLM inference path.

Next

Verify your environment: Prerequisites. Then start the hands-on track.