Secret에서 가져오는 도구의 주소 — 주소에서 키를 읽는 Model Context Protocol 서버
다른 누군가가 운영하는 Model Context Protocol 서버 중 일부는 요청 헤더가 아니라
자신의 주소 — https://mcp.example.com/mcp?api_key=<key> — 에서 키를 읽습니다.
이러한 주소는 일반 주소처럼 도구에 기록할 수 없습니다. 도구는 주소를 기록된 그대로
게시하므로, 주소가 도달하는 모든 파일에 키도 도달하게 됩니다.
이 워크스페이스는 주소를 두 부분으로 나누어 보관합니다. 도구인 core/ai-tool/mcp는
키를 담은 부분을 제외한 주소를 보관합니다. 에이전트에서 도구로의 연결은 전체 주소를
시크릿으로 보관하며, Release가 그 위치를 지정합니다. Kubernetes와 Docker Compose 모두를
대상으로 구성되며, 어느 쪽에서도 렌더링된 파일에 키가 포함되지 않습니다.
에이전트는 이 워크스페이스 자체의 카탈로그에 선언되어 있으므로, 주소를 보관하는 소켓을 여기에 전부 기술합니다. 표준 라이브러리의 에이전트 런타임인 core/ai-agent/openai-agents-sdk, claude-agent-sdk, agent-framework, google-adk, mastra와 플랫폼인 core/ai-agent/flowise, n8n은 같은 두 슬롯을 가진 tools 소켓을 선언합니다. 도구, 두 가지 자격 증명 Features와 그 구현은 표준 라이브러리 카탈로그에 포함되어 제공됩니다.
구성되는 내용
| 인스턴스 | 카탈로그 Component | 여기서의 역할 |
|---|---|---|
search | core/ai-tool/mcp | 다른 곳에서 운영하는 Model Context Protocol 서버로, 아무것도 실행하지 않는 mcp-remote에 매핑됩니다 |
agent | local/ai-agent/mcp-client | 에이전트로, tools 소켓을 통해 search에 연결됩니다 |
두 Releases가 하나의 Aggregate를 공유하며, 각각 자체 Manifest를 가집니다:
| Release | Manifest | 대상 | 전체 주소의 출처 |
|---|---|---|---|
release-helm.yaml | manifest-helm.yaml | Kubernetes | 네임스페이스에 이미 있는 Secret: helm/k8s-existing-secret에 바인딩된 core/referenced-secret |
release-compose.yaml | manifest-compose.yaml | Docker Compose | Compose 변수 참조: compose/dotenv-secret에 바인딩된 core/secret-value |
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example mcp-address-from-secret그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd mcp-address-from-secret빌드
aggrega build --release release-helm.yaml --auto-pull # → dist/kubernetes/aggrega build --release release-compose.yaml --auto-pull # → dist/local/각 Release는 자체 디렉터리에 출력하므로 렌더링된 두 트리가 함께 존재하며 나란히 비교할 수 있습니다.
.aggrega-config.yaml은 에이전트와 그 두 Recipes를 담고 있는 이 워크스페이스 자체의 catalog/를 나열하며, 나머지는 모두 이 파일이 지정하는 기본 레지스트리인 hub.aggrega.ai에서 해석됩니다. 표준 라이브러리 카탈로그의 체크아웃(얻는 곳)을 --catalog로 지정하면 모든 엔터티가 이 두 디렉터리에서 해석되므로, 모든 네트워크 접근을 거부하는 --offline으로도 빌드가 완료됩니다. --auto-pull은 빌드 중에 각 Release의 lockfile을 작성합니다. lockfile과 렌더링된 출력은 생성되는 것이며 배포되지 않습니다.
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>/distcompose 빌드는 release-compose.yaml에 대해 같은 줄을 출력하며, 그 알림은
core/secret-value를 명시하고, 파일 하나를 작성합니다. notice: 줄은 Release가 연결하는
자격 증명 Feature에 관한 것입니다. 이 Feature는 시크릿의 위치 지정자인
origin을 개발자의 values 또는 운영자의 infra에서 받으며,
이 권고는 하나의 리프가 두 축 모두에 선언되어 있음을 알립니다. 이는 어떤 판정도,
렌더링된 어떤 바이트도 바꾸지 않습니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `mcp-address-from-secret` 폴더가 없으면 `example`에 `mcp-address-from-secret` 값을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `mcp-address-from-secret` 폴더에 작성됩니다. 그런 다음 각 Release마다 `release-helm.yaml`, `release-compose.yaml` 순서로 `build` 도구를 한 번씩 호출하되, 매번 `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/mcphelm/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 소켓에 두 개의 시크릿 슬롯을 선언합니다. 설명을 생략한
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는 해당 도구가 자격 증명을 받지 않는다는 연결 자체의 선언이며, 에이전트가 렌더링하는 내용을 전혀 바꾸지 않습니다. 세 가지 모두 연결에 놓이므로, 여러 서버에 접근하는 에이전트는 각 서버의 시크릿을
그 서버의 연결에 보유합니다.
Release는 Aggregate가 연결한 연결에 endpoint를 채웁니다.
release-helm.yaml에서 발췌:
agent: uses: tools: search: features: endpoint: type: core/referenced-secret infra: origin: search-mcp-addressRelease는 values를 작성하지 않으므로 origin은 infra에 있으며, Secret에서 읽는 데이터 키는
Feature의 기본값인 value입니다. Manifest는
core/referenced-secret을 helm/k8s-existing-secret에 바인딩하며, 이는 origin을
네임스페이스에 이미 있는 Secret의 이름으로 읽고 아무것도 렌더링하지 않습니다. Secret은
Release 외부에서, 배포하는 사람이 생성합니다:
kubectl -n agents create secret generic search-mcp-address \ --from-literal=value='https://mcp.example.com/mcp?api_key=<key>'에이전트의 컨테이너는 그 Secret에서 주소를 읽습니다.
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.comMCP_URL_SEARCH는 이름과 데이터 키로 Secret에서 읽은 전체 주소이고,
MCP_HOST_SEARCH는 도구가 게시하는 호스트입니다. dist/kubernetes/helm/에는
에이전트의 Deployment와 도구의 Service만 있습니다. Secret은 렌더링되지 않으며,
키를 담은 파일도 없습니다.
Docker Compose에서
Compose에는 시크릿 참조가 없으므로, 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는 스택이 시작될 때 셸 환경, --env-file로 지정한 파일, 또는
프로젝트 디렉터리의 .env 파일에서 SEARCH_MCP_URL을 치환하므로,
파일에는 참조만 담깁니다.
에이전트의 Recipes가 슬롯을 읽는 방식
tools 소켓의 각 연결은 연결의 별칭을 대문자로 바꾼 이름의 환경 변수가 됩니다. MCP_HOST_<ALIAS>는 도구가 게시하는 호스트에서, MCP_URL_<ALIAS>는 도구가 게시하는 주소에서 만들어집니다. 단, 연결에 endpoint 시크릿이 있으면 MCP_URL_<ALIAS>는 그 시크릿이 되고 게시된 주소는 전혀 전달되지 않습니다. credential을 가진 연결은 MCP_CREDENTIAL_<ALIAS>와, 도구가 그 자격 증명을 제시할 때 쓰도록 게시하는 요청 헤더인 MCP_CREDENTIAL_HEADER_<ALIAS>를 추가합니다.
- Kubernetes에서는 시크릿이 연결과 슬롯을 지정하는 attachment 항목 —
connection: search,from: endpoint,as: env— 이며, provider는helm/k8s-existing-secret이 게시하는 내용에서 Secret의 이름과 데이터 키를 읽어 이를 위의secretKeyRef로 바꿉니다. - Docker Compose에서는 시크릿이 자신의 attachment가 전달한 키인
values.key아래로 에이전트의 inject 파이프에 도착하며, Recipe는 그 값을 서비스의 환경에 씁니다.
대신 도구의 infra.endpoint에 쓰면 키는 게시된 주소가 가는 곳마다 함께 갑니다. 참조 구현은 주소를 쓰인 그대로 게시하므로, 에이전트의 MCP_URL_SEARCH는 Kubernetes에서는 Deployment에, Compose 파일에서는 서비스의 환경에 키를 리터럴 값으로 담게 됩니다.
제한 사항
-
Docker Compose에서는 Release만으로 하나의 에이전트에 연결한 두 시크릿이 충돌합니다. Release가 만드는 각
core/secret-value연결은 Feature의 기본 키인value아래로 전달되므로, 같은 에이전트에 두 번째 연결 — 다른 서버의 주소나 이것과 나란한 자격 증명 — 이 있으면 빌드가 중단됩니다.search에endpoint와credential을 모두 연결하는 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.credentialduplicate 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.키는 Aggregate만 작성하는
values리프이므로, 두 연결 중 하나를 선언하고 그values.key를 지정하는 Aggregate는 이를 피할 수 있습니다: 에이전트의 compose Recipe는 각 시크릿을 해당 연결이 지정한 키 아래에서 읽습니다. Kubernetes에는 이런 제한이 없습니다. 그곳에서 각 시크릿은 키 아래로 전달되는 값이 아니라 이름과 데이터 키로 Secret을 가리키는 참조이기 때문입니다. -
주소의 경로에 있는 키. 서버가 쿼리 문자열이 아니라 경로에서 키를 읽는 경우, 도구의 주소는 경로에서 그 부분을 제거한 주소이며 Secret이 전체 주소를 보관합니다.
-
호스트가 두 번 작성됩니다. 도구의 주소에 평문으로, 그리고 Secret 안에 작성되며, 컴파일러는 Secret을 읽지 않으므로 둘이 일치하는지 확인하는 것은 없습니다.
일반 변수에 $(VAR) 참조를 넣어 실행 시점에 키만으로 주소를 조립하는 방식은
Kubernetes에서만 동작합니다: Kubernetes는 컨테이너에서 그 앞에 나열된 항목으로부터
이러한 참조를 확장하고, helm provider는 Secret에서 읽는 항목을 일반 변수보다 앞에
나열합니다. 반면 Docker Compose는 서비스의 환경 항목 사이에서 $(VAR) 참조를
확장하지 않습니다.
응용하기
- 헤더도 확인하는 서버. 같은 연결에
credential을 연결합니다. 에이전트는MCP_CREDENTIAL_SEARCH와 이를 제시할 헤더인MCP_CREDENTIAL_HEADER_SEARCH를 받습니다. 헤더는 Release가 도구의infra.credential_header에 서버 고유의 헤더를 지정하지 않는 한Authorization입니다. Docker Compose에서는 위에서 설명한 것처럼 두 가지 중 하나의 키를 Aggregate에서 지정합니다. - 여러 서버.
tools소켓에 서버마다 연결을 하나씩 구성합니다. 각 연결의 변수에는 해당 연결의 별칭이 붙으며, 각 연결은 자체 시크릿을 가집니다. - 헤더에서만 키를 읽는 서버.
endpoint를 생략하면MCP_URL_<ALIAS>는 도구가 게시하는 주소가 됩니다.
결정성
두 Releases 모두 --verify-determinism으로 빌드됩니다. 이 옵션은 모든 노드를 두 번 렌더링하고
출력된 바이트를 비교합니다:
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— 에이전트이며,credential슬롯과endpoint슬롯을 가진tools소켓을 정의합니다.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에서 도구 전송 레이블과 함께 설명합니다.