快速入门

本快速入门会创建一个 MCPServer 资源，并验证 operator 会创建对应的 Kubernetes Deployment 和 Service。

先决条件

已安装 Alauda Build 的 MCP Lifecycle Operator。请参见安装。
已为目标集群配置 kubectl。
已将一个 MCP server 镜像推送到目标集群可以拉取的 registry。

创建 MCPServer

应用一个 MCPServer 资源。当前 API 仅支持 spec.source.type 使用 ContainerImage。请将 <registry>/<project>/<mcp-server-image>:<tag> 替换为一个在配置端口上暴露 MCP HTTP endpoint 的 MCP server 镜像。例如，上游 MCP Lifecycle Operator 示例使用的是 quay.io/containers/kubernetes_mcp_server:latest；仅当目标集群可以从 quay.io 拉取镜像时才使用该镜像。

kubectl apply -f - <<EOF
apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: kubernetes-mcp-server
  namespace: default
spec:
  source:
    type: ContainerImage
    containerImage:
      ref: <registry>/<project>/<mcp-server-image>:<tag>
  config:
    port: 8080
EOF

operator 会在同一命名空间中创建一个名为 kubernetes-mcp-server 的 Deployment 和 Service。

验证 MCPServer

检查 MCPServer 状态：

kubectl get mcpservers -n default
kubectl get mcpserver kubernetes-mcp-server -n default -o yaml

kubectl get mcpservers 的预期输出：

NAME                    READY   ACCEPTED   IMAGE                                           PORT   ADDRESS                                                        AGE
kubernetes-mcp-server   True    True       <registry>/<project>/<mcp-server-image>:<tag>    8080   http://kubernetes-mcp-server.default.svc.cluster.local:8080/mcp   1m

ADDRESS 列是其他工作负载可以调用的集群内部 MCP 端点。

验证受管资源：

kubectl get deployment kubernetes-mcp-server -n default
kubectl get service kubernetes-mcp-server -n default
kubectl get pods -n default -l mcp-server=kubernetes-mcp-server

Deployment 应处于可用状态，Service 应已存在，且 pods 应为 Running。

测试端点

转发生成的 Service：

kubectl port-forward service/kubernetes-mcp-server 8080:8080 -n default

在另一个终端中测试 server：

curl http://localhost:8080/healthz
curl http://localhost:8080/mcp

确切的响应取决于 MCP server 镜像。端点可访问即可确认 operator 创建的 Service 正在将流量路由到 MCP server pod。

更新端口或路径

默认的 MCP 路径为 /mcp。如果要显式设置该路径或更改端口，请更新 spec.config：

kubectl patch mcpserver kubernetes-mcp-server -n default --type merge -p '{
  "spec": {
    "config": {
      "port": 9090,
      "path": "/mcp"
    }
  }
}'

调和完成后，验证更新后的地址：

kubectl get mcpserver kubernetes-mcp-server -n default
kubectl get service kubernetes-mcp-server -n default

常见配置

使用 spec.config 配置容器级设置，例如参数、环境变量和挂载的配置：

spec:
  source:
    type: ContainerImage
    containerImage:
      ref: <registry>/<project>/<mcp-server-image>:<tag>
  config:
    port: 8080
    path: /mcp
    arguments:
      - --config
      - /etc/mcp/config.toml
    env:
      - name: LOG_LEVEL
        value: info
      - name: API_KEY
        valueFrom:
          secretKeyRef:
            name: mcp-server-secret
            key: api-key
    storage:
      - path: /etc/mcp
        permissions: ReadOnly
        source:
          type: ConfigMap
          configMap:
            name: mcp-server-config

引用的 ConfigMaps 和 Secrets 必须与 MCPServer 位于同一命名空间中。

使用 spec.runtime 配置生成的 Deployment：

spec:
  runtime:
    replicas: 2
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 256Mi
    health:
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
      readinessProbe:
        httpGet:
          path: /healthz
          port: 8080

当 MCP server 需要特定的 Kubernetes service account 或更严格的 pod 设置时，使用 spec.runtime.security：

spec:
  runtime:
    security:
      serviceAccountName: mcp-server
      podSecurityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        runAsNonRoot: true
        capabilities:
          drop:
            - ALL

如果 MCP server 不保留按客户端划分的会话状态，请将 spec.mcp.stateless 设置为 true，这样生成的 Service 就可以在多个副本之间自由进行负载均衡：

spec:
  runtime:
    replicas: 3
  mcp:
    stateless: true

清理

删除 MCPServer 资源：

kubectl delete mcpserver kubernetes-mcp-server -n default

operator 会移除受管的 Deployment 和 Service。

#快速入门

#目录

#先决条件

#创建 MCPServer

#验证 MCPServer

#测试端点

#更新端口或路径

#常见配置

#清理