Basic MCP Server

Deploy an MCP server on Kubernetes and connect to it through agentgateway using the Kubernetes Gateway API.

What you’ll build

In this tutorial, you will:

Set up a local Kubernetes cluster using kind
Install the agentgateway control plane
Deploy an MCP server as a Kubernetes service
Create an AgentgatewayBackend to connect to the MCP server
Route MCP traffic through agentgateway and test tool calls

Before you begin

Make sure you have the following tools installed:

For detailed installation instructions for each tool, see the LLM Gateway tutorial.

Step 1: Create a kind cluster

kind create cluster --name agentgateway

Verify the cluster is running:

kubectl cluster-info --context kind-agentgateway

Step 2: Install agentgateway

Install the Gateway API CRDs, agentgateway CRDs, and the control plane.

# Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

# agentgateway CRDs
helm upgrade -i --create-namespace \
  --namespace agentgateway-system \
  --version v2.3.0-main agentgateway-crds oci://ghcr.io/kgateway-dev/charts/agentgateway-crds

# Control plane
helm upgrade -i -n agentgateway-system agentgateway oci://ghcr.io/kgateway-dev/charts/agentgateway \
  --version v2.3.0-main

Verify the control plane is running:

kubectl get pods -n agentgateway-system

Step 3: Create a Gateway

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agentgateway-proxy
  namespace: agentgateway-system
spec:
  gatewayClassName: agentgateway
  listeners:
  - protocol: HTTP
    port: 80
    name: http
    allowedRoutes:
      namespaces:
        from: All
EOF

Wait for the proxy to be ready:

kubectl get gateway agentgateway-proxy -n agentgateway-system
kubectl get deployment agentgateway-proxy -n agentgateway-system

Step 4: Deploy an MCP server

Deploy the MCP “everything” server as a Kubernetes Deployment and Service. This server provides sample tools like echo, add, and longRunningOperation.

kubectl apply -f- <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server-everything
  namespace: agentgateway-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcp-server-everything
  template:
    metadata:
      labels:
        app: mcp-server-everything
    spec:
      containers:
      - name: mcp-server
        image: node:22-alpine
        command: ["npx", "-y", "mcp-proxy", "--port", "8080", "--", "npx", "-y", "@modelcontextprotocol/server-everything"]
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-server-everything
  namespace: agentgateway-system
spec:
  selector:
    app: mcp-server-everything
  ports:
  - port: 80
    targetPort: 8080
    appProtocol: kgateway.dev/mcp
EOF

Wait for the MCP server pod to be ready. The first startup may take a minute as it downloads the npm packages.

kubectl get pods -n agentgateway-system -l app=mcp-server-everything -w

Step 5: Create the MCP backend

Create an AgentgatewayBackend resource that connects to the MCP server using dynamic service discovery.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: mcp-backend
  namespace: agentgateway-system
spec:
  mcp:
    selector:
      services:
        matchLabels:
          app: mcp-server-everything
EOF

Step 6: Create the HTTPRoute

Route MCP traffic through the agentgateway proxy to the backend.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp
  namespace: agentgateway-system
spec:
  parentRefs:
    - name: agentgateway-proxy
      namespace: agentgateway-system
  rules:
    - backendRefs:
      - name: mcp-backend
        namespace: agentgateway-system
        group: agentgateway.dev
        kind: AgentgatewayBackend
EOF

Step 7: Test the MCP connection

Set up port-forwarding:

kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 8080:80 &

Initialize an MCP session:

curl -s -i http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

Copy the mcp-session-id from the response headers, then list available tools:

curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

You should see tools like echo, add, longRunningOperation, and more.

Call a tool

curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello from Kubernetes!"}},"id":3}'

Example output:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "Echo: Hello from Kubernetes!"}]
  }
}

Cleanup

kill %1 2>/dev/null
kind delete cluster --name agentgateway

Next steps

MCP Federation

Federate multiple MCP servers

JWT Authorization

Secure with JWT authentication

MCP Documentation

Complete MCP configuration reference