跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

从 Secret 获取工具的地址——从自身地址读取密钥的 Model Context Protocol 服务器

有些由他人运行的 Model Context Protocol 服务器从自己的地址中读取密钥——https://mcp.example.com/mcp?api_key=<key>——而不是从请求头中读取。这样的地址不能像普通地址那样写入工具:工具会按原样发布其地址,因此密钥会到达该地址所到达的每一个文件。

此工作区将地址分为两部分保存。工具 core/ai-tool/mcp 保存不含密钥部分的地址。智能体到该工具的连接将完整地址作为密钥保存,并由 Release 指明其存放位置。它可以为 Kubernetes 和 Docker Compose 构建,并且在两者上,任何渲染出的文件都不包含该密钥。

智能体在此工作区自己的目录中声明,因此保存地址的 socket 在这里完整写出。标准库中的智能体运行时 core/ai-agent/openai-agents-sdk、claude-agent-sdk、agent-framework、google-adk 和 mastra,以及平台 core/ai-agent/flowise 和 n8n,都声明了带有相同两个 slot 的 tools socket。该工具、两个凭据 Features 及其实现都随标准库目录提供。

它构建了什么

实例目录中的 Component它在此处的角色
searchcore/ai-tool/mcp由他人运行的 Model Context Protocol 服务器,映射到 mcp-remote,后者不运行任何东西
agentlocal/ai-agent/mcp-client智能体,通过其 tools 插槽连接到 search

两个 Releases 共用同一个 Aggregate,各自拥有自己的 Manifest:

ReleaseManifest目标完整地址的来源
release-helm.yamlmanifest-helm.yamlKubernetes命名空间中已有的 Secret:core/referenced-secret 绑定到 helm/k8s-existing-secret
release-compose.yamlmanifest-compose.yamlDocker ComposeCompose 变量引用:core/secret-value 绑定到 compose/dotenv-secret

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example mcp-address-from-secret

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd mcp-address-from-secret

构建

Terminal window
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/
aggrega build --release release-compose.yaml --auto-pull # → dist/local/

每个 Release 写入各自的目录,因此两棵渲染出的目录树可以共存, 并可并排比较。

.aggrega-config.yaml 列出本工作区自己的 catalog/,其中包含该代理及其两个 Recipes;其余一切从它指定的默认注册表 hub.aggrega.ai 解析。若用 --catalog 指定标准库目录的检出(获取途径),每个实体都从这两个目录解析,因此构建在 --offline 下也能完成,该选项拒绝任何网络访问。--auto-pull 在构建期间写入每个 Release 的锁文件;锁文件和渲染输出都是生成的,而不随仓库提供。

Kubernetes 构建会打印以下内容,其中 <workspace> 代表本示例的 文件夹:

Pull complete: release-helm.lock (entities=11, source_artifacts=0, external_inputs=0)
notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 2 files written to <workspace>/dist

compose 构建会为 release-compose.yaml 打印相同的几行,其通知 指明 core/secret-value,并写入一个文件。notice: 一行针对的是该 Release 附加的凭据 Feature:它从开发者的 values 或运维者的 infra 接受该 secret 的定位符 origin,而该提示报告有一个叶子在两个支柱中都有声明。它不改变任何判定, 也不改变任何渲染出的字节。

借助 AI 助手

已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。

只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `mcp-address-from-secret` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `mcp-address-from-secret`,不设 `dir`:它会把示例写入一个新的 `mcp-address-from-secret` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-helm.yaml` 和 `release-compose.yaml`——每次都将 `workspace_root` 设为 `mcp-address-from-secret`、`release` 设为该文件、`auto_pull` 设为 true、`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `mcp-address-from-secret/dist/` 下。

工具持有不含密钥的地址

摘自 release-helm.yaml:

search:
infra:
endpoint: https://mcp.example.com/mcp

helm/mcp-remote 从该地址中读取它发布的主机、端口和协议,并为该工具生成一个文件:一个将集群内名称映射到该主机的 ExternalName Service。 dist/kubernetes/helm/search-service.yaml 的完整 spec:

spec:
type: ExternalName
externalName: mcp.example.com
ports:
- port: 443

因此,工具持有的地址至少需要协议和主机,且不包含携带密钥的那一部分。compose/mcp-remote 完全不为该工具定义服务。

代理的连接持有完整地址

代理的 Component 在其 tools 套接字上声明了两个 secret 槽位。摘自 catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml,省略了描述:

tools:
selector: "component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http"
valueSchema:
unauthenticated:
type: boolean
default: false
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
endpoint:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

credential 持有代理在请求头中出示的密钥;endpoint 持有 完整地址,供从地址本身读取密钥的服务器使用。 unauthenticated 是连接自身声明其工具不需要 凭据,不改变代理渲染的任何内容。三者都位于 连接上,因此访问多个服务器的代理会在各服务器的连接上 持有该服务器的 secret。

Release 在 Aggregate 所连接的连接上填充 endpoint。摘自 release-helm.yaml:

agent:
uses:
tools:
search:
features:
endpoint:
type: core/referenced-secret
infra:
origin: search-mcp-address

Release 不写 values,因此 origin 位于 infra 中,从 Secret 读取的数据键 是该 Feature 的默认值 value。Manifest 将 core/referenced-secret 绑定到 helm/k8s-existing-secret,后者将 origin 读作 命名空间中已有的 Secret 的名称,并且不渲染任何内容。该 Secret 在 Release 之外,由部署它的人创建:

Terminal window
kubectl -n agents create secret generic search-mcp-address \
--from-literal=value='https://mcp.example.com/mcp?api_key=<key>'

代理的容器从中读取地址。 dist/kubernetes/helm/agent-deployment.yaml 的 env:

env:
- name: MCP_URL_SEARCH
valueFrom:
secretKeyRef:
name: search-mcp-address
key: value
- name: MCP_HOST_SEARCH
value: mcp.example.com

MCP_URL_SEARCH 是完整地址,按名称和数据键从 Secret 读取; MCP_HOST_SEARCH 是工具发布的主机。dist/kubernetes/helm/ 只包含 代理的 Deployment 和工具的 Service:不渲染任何 Secret, 也没有任何文件携带密钥。

在 Docker Compose 上

Compose 没有 secret 引用,因此 compose 的 Release 用 core/secret-value 填充同一槽位,其 origin 为一个 Compose 变量引用。摘自 release-compose.yaml:

agent:
uses:
tools:
search:
features:
endpoint:
type: core/secret-value
infra:
origin: "${SEARCH_MCP_URL}"

compose/dotenv-secret 按原样传递该引用,由代理的 服务携带。dist/local/compose/docker-compose.yaml 中 agent 服务的 environment, 该文件只定义这一个服务:

environment:
MCP_HOST_SEARCH: mcp.example.com
MCP_URL_SEARCH: ${SEARCH_MCP_URL}

Docker Compose 在栈启动时替换 SEARCH_MCP_URL——来源可以是 shell 环境、用 --env-file 指定的文件,或项目目录中的 .env 文件——因此文件中只携带该引用。

agent 的 Recipes 如何读取该槽位

tools socket 上的每个连接都会变成以该连接别名的大写形式命名的环境变量:MCP_HOST_<ALIAS> 来自工具发布的主机,MCP_URL_<ALIAS> 来自工具发布的地址——除非该连接带有 endpoint secret,此时 MCP_URL_<ALIAS> 就是该 secret,而发布的地址完全不会被传递。带有 credential 的连接会添加 MCP_CREDENTIAL_<ALIAS>,以及 MCP_CREDENTIAL_HEADER_<ALIAS>,即工具发布的、用于出示该凭据的请求头。

  • 在 Kubernetes 上,secret 是一个指明连接和槽位的 attachment 条目——connection: search、from: endpoint、as: env——provider 将其转换为上文的 secretKeyRef,并从 helm/k8s-existing-secret 发布的内容中读取 Secret 的名称和数据键。
  • 在 Docker Compose 上,secret 通过 agent 的 inject 管道到达,所用的键是其自身 attachment 传递它时所用的键 values.key,Recipe 再将该值写入服务的环境中。

如果改为写入工具的 infra.endpoint,密钥就会随发布的地址一起去往任何地方:agent 的 MCP_URL_SEARCH 会以字面值的形式携带它,在 Kubernetes 上位于 Deployment 中,在 Compose 文件中位于服务的环境中,因为参考实现会按原样发布该地址。

限制

  • 在 Docker Compose 上,仅由 Release 挂接到同一个 agent 的两个 secret 会冲突。 Release 所做的每个 core/secret-value 挂接都以该 Feature 的默认键 value 交付,因此同一个 agent 上的第二个挂接——另一个服务器的地址,或与此并列的一个凭据——会使构建中止。一个将 endpoint 和 credential 都挂接到 search 的 Release 会输出:

    [… omitted: what resolving the lockfile prints, the same halt among it, and the notice about core/secret-value]
    [OPS_ERROR E0318] release-compose.yaml at .spec.boundaries.main.components.agent.uses.tools.search.features.credential
    duplicate delivery key across two attachments: an attachment's FeatureRecipe writes a delivery key another attachment already delivered ("value", mechanism "env", attachment "search.credential", delivered first by attachment "search.endpoint"). Give one of the two attachments a key of its own, or attach one fewer: the key this attachment delivers under is chosen by its FeatureRecipe, which can read the attachment's own values and infra, and the other's is chosen the same way or by its own inject block where it delivered through one. A Release sets an attachment's infra and never its values, so where a key is chosen by a value, attach that attachment in the Aggregate with the value, and keep giving the rest from the Release.

    该键是一个 values 叶子,只有 Aggregate 会写入它,因此由 Aggregate 声明两个挂接之一并为其命名 values.key,即可避免冲突:agent 的 compose Recipe 会按各自挂接所命名的键读取每个 secret。Kubernetes 没有这一限制,因为在那里每个 secret 都是按名称和数据键对某个 Secret 的引用,而不是以某个键交付的值。

  • 地址路径中的密钥。 如果服务器从路径而不是查询字符串中读取密钥,则工具的地址是去掉路径中该部分后的地址,而 Secret 保存完整地址。

  • 主机被写了两次,一次以明文写在工具的地址中,一次写在 Secret 内部,且没有任何检查确保两者一致,因为编译器从不读取 Secret。

在运行时仅凭密钥组装地址,即在普通变量中使用 $(VAR) 引用,只在 Kubernetes 上可行:Kubernetes 会根据容器中排在该引用之前的条目展开这样的引用,而 helm provider 会把从 Secret 读取的条目排在普通变量之前;Docker Compose 则不会在服务的环境条目之间展开任何 $(VAR) 引用。

改编示例

  • 同时还检查请求头的服务器。 在同一个连接上挂接 credential。agent 会收到 MCP_CREDENTIAL_SEARCH,以及用于提交它的请求头 MCP_CREDENTIAL_HEADER_SEARCH:默认为 Authorization,除非 Release 在该工具的 infra.credential_header 中指定服务器自己的请求头。 在 Docker Compose 上,如上所述,在 Aggregate 中为两者之一指定键。
  • 多个服务器。 在 tools 套接字上为每个服务器接入一个连接。 每个连接的变量都带有其别名,每个连接持有各自的 secret。
  • 只从请求头读取密钥的服务器。 省略 endpoint, MCP_URL_<ALIAS> 即为该工具发布的地址。

确定性

两个 Releases 均在 --verify-determinism 下构建,该选项会将每个节点渲染两次, 并比较输出的字节:

Terminal window
aggrega build --release release-helm.yaml --verify-determinism

从干净的目录树重新构建其中任一个,都会逐字节重现其渲染输出。

文件

  • aggregate.yaml — 工具和智能体,通过 tools 插槽连接, 未附加任何密钥。
  • manifest-helm.yaml、manifest-compose.yaml — 将工具映射到 mcp-remote,将 智能体映射到它自己的 Recipe,以及每个目标使用的凭据 Feature。
  • release-helm.yaml、release-compose.yaml — 不含密钥的工具地址、 智能体的镜像,以及智能体连接上的 endpoint 密钥。
  • catalog/component/local/ai-agent/mcp-client/1.0.0/component.yaml — 智能体:它的 tools 插槽,带有 credential 和 endpoint 槽位。
  • catalog/recipe/helm/mcp-client/1.0.0/recipe.yaml、 catalog/recipe/compose/mcp-client/1.0.0/recipe.yaml — 每个目标上的 智能体。
  • .aggrega-config.yaml — 目录搜索栈和注册表。
  • build-release.sh — 构建一个 Release,并输出等效的 aggrega build 命令。

关于智能体在请求头中提供、并保存在其所提供的连接上的密钥, 请参阅 connection-credentials。两者背后的 模型是凭据模型, 工具的实现方式在 AI Features 中结合工具传输标签进行了说明。