快速开始

此快速开始将创建一个 MCPServer 资源,并验证 operator 是否创建了对应的 Kubernetes Deployment 和 Service。

前提条件

  • 已安装 Alauda Build of MCP Lifecycle Operator。请参阅 Installation。
  • 已为目标集群配置 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 会在同一 namespace 中创建一个名为 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 endpoint,其他工作负载可以调用该 endpoint。

验证受管资源:

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。

测试 Endpoint

转发生成的 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 镜像。只要 endpoint 可达,就可以确认 operator 创建的 Service 能够将流量路由到 MCP server pod。

更新端口或路径

默认的 MCP path 是 /mcp。如需显式设置该 path 或更改端口,请更新 spec.config:

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

在 reconciliation 完成后,验证更新后的地址:

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

常见配置

使用 spec.config 配置容器级别设置,例如 arguments、environment variables 和挂载的配置:

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 相同的 namespace 中。

使用 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 不保存每个客户端的 session state,请将 spec.mcp.stateless: true,这样生成的 Service 就可以在各个副本之间自由进行负载均衡:

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

清理

删除 MCPServer 资源:

kubectl delete mcpserver kubernetes-mcp-server -n default

operator 会移除受管的 Deployment 和 Service。