第一次接入 AI Gateway MCP
本地 soha CLI 和 MCP server 都是 Gateway client。它们不会直接读取 PostgreSQL、kubeconfig、Docker 或 runner workspace。所有 tool call、resource read 和 prompt read 都会回到后端 AI Gateway 边界。
前置条件
- 已按 第一次部署 启动 Soha 控制平面。
- 本地
PATH中已经可以执行sohaCLI。 - 当前用户或 service account 拥有
ai.gateway.view;如果要调用工具,还需要ai.gateway.invoke。
登录
soha login \
--server http://localhost:8080 \
--login admin \
--profile gateway-admin \
--ai-client soha-admin \
--ai-client-id soha-admin读取 Capability
soha capabilities --profile gateway-admin
soha capabilities --profile gateway-admin --output names对应的后端 API reference 名称是 GET /api/v1/ai-gateway/capabilities。
生成 MCP 配置
soha mcp install --profile gateway-admin --command /usr/local/bin/soha生成的配置会让客户端启动:
soha mcp start --profile gateway-adminCodex、Cursor 和 Claude Code 的示例见 AI Gateway 示例。
验证 Resource 和 Prompt 读取
soha resource read soha://delivery/applications --profile gateway-admin
soha prompt get soha.delivery.plan_release --profile gateway-admin这些命令仍然会通过 POST /api/v1/ai-gateway/resources/read 和 POST /api/v1/ai-gateway/prompts/get 代理到后端。
预期输出形状
Capability 列表会按权限过滤。配置正确的 profile 和 MCP command 应该能输出形状兼容的结果,并且不会暴露 access token:
Fixture artifact: first-ai-gateway-mcp.expected.txt
soha login
soha capabilities --profile gateway-admin --output names
soha resource read soha://delivery/applications --profile gateway-admin
soha prompt get soha.delivery.plan_release --profile gateway-adminprofile: gateway-admin
delivery.actions.trigger
k8s.pods.list
resource: soha://delivery/applications
prompt: soha.delivery.plan_release验收标准
soha login能保存本地 profile,后续 profile 输出不会把 token 打印回来。soha capabilities返回经过权限过滤的 manifest。- MCP client config 启动的是
soha mcp start,不是直接数据库或集群进程。 - Resource 和 prompt 读取要么返回脱敏内容,要么返回清晰的权限或 binding 错误。
已知缺口
AI client、grant、access policy 和 skill binding 的 Gateway 管理端点已经在控制平面和 Console 中实现,但其中若干管理接口仍标记为待补公开 OpenAPI contract,详见 Core Endpoints。
Last updated on