Nhập cấu hình của một client MCP
Hướng dẫn từng bước này nhập các máy chủ Model Context Protocol mà một trợ lý lập trình được cấu hình — hai máy chủ nó khởi động từ dòng lệnh và một máy chủ do người khác vận hành — và build các máy chủ cho Kubernetes, để một tác tử chạy trong cluster có thể tiếp cận cùng các công cụ đó. Quá trình nhập soạn bản nháp mọi tệp mà bản build đọc: dòng lệnh hoặc địa chỉ của mỗi máy chủ, phần hiện thực hóa chạy nó, và nguồn gốc token của máy chủ GitHub. Mọi tệp và mọi khối đầu ra dưới đây đều đến từ một lần chạy thực; cấu hình và từng giai đoạn của hướng dẫn nằm trong ví dụ import-mcp, nơi một script kiểm tra chạy lại quá trình nhập, so sánh những gì nó ghi, những gì nó in ra và các khối mà trang này trích dẫn với các tệp được lưu ở đó, rồi xác thực và build những gì quá trình nhập đã ghi.
Tạo ví dụ
Bạn có thể chạy lần nhập này bằng các lệnh trên trang này, hoặc để trợ lý AI của bạn chạy giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example import-mcpSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới; lệnh tiếp sau đó, ở bên dưới, chuyển vào thư mục source của thư mục mới, nơi chứa những gì trang này nhập và là nơi chạy lệnh nhập:
cd import-mcp
Cấu hình
Tệp .mcp.json của Claude Code, ở thư mục gốc của một dự án:
{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }, "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "docs-search": { "type": "http", "url": "https://mcp.example.com/docs/mcp", "headers": { "Authorization": "Bearer ${DOCS_API_KEY}" } } }}Quá trình nhập đọc theo cùng cách tệp claude_desktop_config.json của Claude Desktop, .cursor/mcp.json của Cursor, .vscode/mcp.json của Visual Studio Code và một tệp server.json của registry MCP. Bên cạnh cấu hình, một tệp .aggrega-config.yaml biến thư mục thành một không gian làm việc:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside .mcp.json.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.ai--target soạn nháp một Manifest từ các Recipes của danh mục. Không gian làm việc không chỉ định thư mục danh mục nào, vì vậy quá trình nhập đọc danh mục thư viện chuẩn từ registry mà từ đó nó tải trình nhập của mình về: một bản chụp nhanh có chữ ký của danh mục đã phát hành, được lần nhập đầu tiên tải về, xác minh và lưu trong bộ nhớ đệm nội dung của không gian làm việc, và được nêu tên theo digest của nó trong bản ghi mà quá trình nhập ghi bên cạnh các bản nháp. Một không gian làm việc chỉ định các thư mục danh mục riêng — trong AGGREGA_CATALOG_DIRS, hoặc dưới workspace.catalog_dirs — thì thay vào đó nhập dựa trên các thư mục đó.
Tệp câu trả lời
Trên Kubernetes, máy chủ GitHub đọc token của nó từ một Secret do cluster lưu giữ, và không cấu hình MCP nào nêu tên Secret đó: cấu hình đọc token từ GITHUB_TOKEN trong shell của bạn. Vì vậy quá trình nhập hỏi tên của Secret. Ví dụ giữ câu trả lời trong import-answers.yaml, bên cạnh .mcp.json, nơi quá trình nhập tìm nó:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.github.features.server_env.infra.origin: "github-mcp-token"Quá trình nhập đã tự ghi tệp này vào lần đầu tiên nó được chạy mà không có câu trả lời: không có terminal để hỏi, nó soạn nháp mọi thứ khác, để trống tên của Secret, liệt kê khóa trong tệp và dừng lại với
1 value the drafts leave empty is still owed, listed in the answers file <workspace>/import-answers.yaml: write it beside its key there, then run the import againTại một terminal, thay vào đó nó đặt câu hỏi và ghi câu trả lời vào tệp cho lần nhập tiếp theo. Câu trả lời là tên của Secret, github-mcp-token, không bao giờ là token. Tệp câu trả lời của quá trình nhập mô tả đầy đủ tệp và các câu hỏi.
aggrega import liệt kê mọi cờ mà lệnh nhận, trong đó có --answers, cờ nêu tên một tệp câu trả lời được lưu ở nơi khác.
Chuyển vào source:
cd sourceChạy lệnh nhập
aggrega import .mcp.json --target helmTrên đầu ra chuẩn, nó liệt kê những gì đã ghi:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonTrên luồng lỗi chuẩn, với <workspace> đại diện cho thư mục nơi bạn đã chạy nó:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the mcp format, with drafted paths relative to <workspace>warn: the value of infra.stdio_command.0 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.1 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.2 of node github is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.0 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.stdio_command.1 of node fetch is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of headers.Authorization of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptywarn: the value of infra.endpoint of node docs-search is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptyPull complete: <workspace>/release.lock (entities=7, source_artifacts=0, external_inputs=0)
Mỗi máy chủ là một instance của công cụ MCP trong thư viện chuẩn, core/ai-tool/mcp, nên quá trình nhập không cân nhắc ứng viên nào và không in dòng mapped nào.
- Các dòng
warnnêu tên các giá trị mà cấu hình của một máy chủ chứa. Không client MCP nào đánh dấu bất kỳ giá trị nào trong số đó là thông tin xác thực, và bất kỳ giá trị nào cũng có thể mang một thông tin như vậy — một khóa trong đối số dòng lệnh, một token trong địa chỉ — nên quá trình nhập nêu tên từng mục của dòng lệnh, từng header và từng địa chỉ mà cấu hình mang, theo máy chủ và vị trí của nó, không bao giờ theo giá trị. Hãy đọc chúng trước khi bạn chia sẻ bản nháp. Trongenv, giá trị${GITHUB_TOKEN}chỉ là một tham chiếu biến, nên nó không chứa giá trị riêng và không cảnh báo nào nêu tên nó. - Dòng
Pull completelà quá trình nhập đang tải những gì mà Release bản nháp phụ thuộc vào, nhưaggrega pulllàm, vàorelease.lock, để các bản nháp được xác thực và build ngay lập tức. Với--offline, quá trình nhập không tải gì và nêu lệnhaggrega pullcần chạy.
Những gì được ghi
Aggregate, Release và Manifest được đặt tên imported/mcp, theo tệp, .mcp.json, vì cấu hình của một client không mang tên riêng — server.json của một registry được đặt tên theo name của nó — dưới namespace mà thiết lập target_namespace của trình nhập đặt ra, là imported trừ khi bạn đặt namespace khác (Thiết lập).
aggregate.yaml — mỗi máy chủ một instance, và chưa có gì sử dụng chúng:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/mcp version: 0.1.0 description: Draft Aggregate imported from a source in the mcp format.spec: components: github: type: core/ai-tool/mcp fetch: type: core/ai-tool/mcp docs-search: type: core/ai-tool/mcprelease.yaml — cách mỗi máy chủ được chạy hoặc được tiếp cận, đúng như cấu hình nêu, và Secret mà token của máy chủ GitHub được đọc từ đó:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/mcp # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the mcp format.spec: aggregate: imported/mcp manifest: imported/mcp components: github: infra: stdio_command: - "npx" - "-y" - "@modelcontextprotocol/server-github" stdio_runtime: npm features: server_env: type: core/referenced-secret infra: # Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding the environment github is started with, one data key per variable, each named as the variable it holds: GITHUB_PERSONAL_ACCESS_TOKEN. origin: "github-mcp-token" fetch: infra: stdio_command: - "uvx" - "mcp-server-fetch" stdio_runtime: pypi # The headers the source sends this server, which no infrastructure key of core/ai-tool/mcp takes, since a remote server's credential is held by each consumer, on its connection to the tool: # - Authorization: "Bearer ${DOCS_API_KEY}" docs-search: infra: endpoint: "https://mcp.example.com/docs/mcp"- Môi trường,
development, là giá trị mặc định mà quá trình nhập ghi ra vì không cấu hình nào chỉ định môi trường; hãy thay đổi nó nếu Release được triển khai ở nơi khác. stdio_runtimeđược đọc ra từ mỗi lệnh:npxchạy một gói npm,uvxchạy một gói PyPI.- Token GitHub. Môi trường của máy chủ trở thành slot
server_envcủa nó. Trên Kubernetes, bản hiện thực hóa củacore/referenced-secret-set,helm/k8s-secret-set, ghi các giá trị nó nhận được vào một Secret mà bản build render, điều này sẽ đặt token vào một tệp. Vì vậy, với--target helm, quá trình nhập gắncore/referenced-secretthay vào đó, chỉ định một Secret mà cluster đã có sẵn — câu trả lời,github-mcp-token— với một khóa dữ liệu cho mỗi biến,GITHUB_PERSONAL_ACCESS_TOKEN. Bridge nhập mọi khóa dữ liệu của Secret đó thành một biến cùng tên, nên máy chủ đọc token của nó như khi chạy trên máy của bạn, và không tệp render nào chứa nó. - Header
Authorizationvẫn là một chú thích. Thông tin xác thực của một máy chủ từ xa do bên gọi nó nắm giữ, trên chính kết nối của bên gọi đó tới công cụ, và không gian làm việc này chưa có bên gọi nào. Khi bạn nối một tác tử tớidocs-search, header sẽ được đặt trên kết nối đó.
manifest.yaml — một bản hiện thực hóa cho mỗi máy chủ, theo tên của nó, và bản hiện thực hóa của Secret:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/mcp version: 0.1.0spec: mappings: components: type: {} name: github: helm/mcp-stdio-bridge fetch: helm/mcp-stdio-bridge docs-search: helm/mcp-remote features: type: core/referenced-secret: helm/k8s-existing-secretBa Recipes Kubernetes hiện thực hóa core/ai-tool/mcp — một cho máy chủ được phát hành dưới dạng image, một cho gói chạy sau một bridge, một cho máy chủ do người khác vận hành — và cái nào phù hợp là một thuộc tính của từng máy chủ, do cấu hình nêu. Vì vậy quá trình nhập ánh xạ mỗi instance theo tên của nó: github và fetch, được khởi động từ dòng lệnh, chạy sau bridge stdio, helm/mcp-stdio-bridge; docs-search, do người khác vận hành, được ánh xạ tới helm/mcp-remote, thứ không chạy gì cả và công bố địa chỉ. Secret của token được ánh xạ tới helm/k8s-existing-secret, thứ tham chiếu một Secret thay vì ghi ra một Secret.
release.lock ghi lại, theo digest, các thực thể danh mục mà Release đã được phân giải tới, và .aggrega-import.json là bản ghi về những gì quá trình nhập đã ghi, được một lệnh aggrega import --sync sau đó đọc.
Trên Docker Compose
Các máy chủ cũng chạy trên Docker Compose. aggrega import .mcp.json --target compose ánh xạ github và fetch tới compose/mcp-stdio-bridge và docs-search tới compose/mcp-remote, đồng thời giữ môi trường của máy chủ GitHub đúng như cấu hình viết: một mục core/referenced-secret-set có giá trị là tham chiếu biến ${GITHUB_TOKEN}, được hiện thực hóa bởi compose/dotenv-secret-set, thứ ghi nó vào môi trường của dịch vụ đúng như đã viết, để Docker Compose điền nó từ shell của bạn khi stack khởi động. Quá trình nhập đó không hỏi gì, và giữ tên của Secret trong tệp câu trả lời mà không sử dụng nó.
Xác thực và dựng
aggrega validate --release release.yamlaggrega build --release release.yaml

Bước xác thực in ra:
notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)và bản dựng, với <workspace> đại diện cho thư mục mà bạn đã chạy nó:
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: 5 files written to <workspace>/distDòng notice mang tính khuyến nghị: Feature chấp nhận origin của nó từ values của Aggregate hoặc infra của Release, và thông báo cho biết một lá được khai báo ở cả hai. Nó không thay đổi phán quyết nào.
Bản build ghi, dưới dist/helm/, một Deployment và một Service cho mỗi máy chủ trong hai máy chủ chạy qua bridge, và một Service cho docs-search. Container của máy chủ GitHub, trong dist/helm/github-deployment.yaml, chạy bridge với dòng lệnh của máy chủ, và lấy môi trường của nó từ Secret:
containers: - name: main image: ghcr.io/supercorp-ai/supergateway:4.1.0@sha256:1938c43538a5308bce07d58028e9de00b7acfecb40b39b059b2f3931800ad910 args: - --stdio - '''npx'' ''-y'' ''@modelcontextprotocol/server-github''' - --outputTransport - streamableHttp - --stateful - --port - "8080" - --streamableHttpPath - /mcp - --healthEndpoint - /healthz ports: - name: http containerPort: 8080 env: - name: MCP_TOOL_SIDE_EFFECTS value: mutating - name: MCP_TOOL_TIMEOUT_SECONDS value: "30" - name: MCP_TOOL_PORT value: "8080" envFrom: - secretRef: name: github-mcp-token [… omitted: the container's resources and its readiness probe]dist/helm/docs-search-service.yaml không chạy gì cả: nó đặt cho máy chủ do người khác vận hành một tên bên trong cluster.
apiVersion: v1kind: Servicemetadata: name: docs-search [… omitted: the labels and annotations the build writes on every resource]spec: type: ExternalName externalName: mcp.example.com ports: - port: 443Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega có thể làm điều tương tự: dán prompt này vào nó.
Chỉ dùng các công cụ của Aggrega, và không tự tạo thư mục nào. Nếu thư mục Workspace chưa có thư mục `import-mcp`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `import-mcp` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `import-mcp` mới, trong đó thư mục `source` chứa những gì trang này nhập. Sau đó gọi công cụ `import` với `workspace_root` đặt thành `import-mcp/source`, `source` đặt thành `.mcp.json` và `target` đặt thành `helm`: công cụ này đọc các câu trả lời cần thiết từ `import-answers.yaml` bên cạnh `.mcp.json`, ghi các bản nháp vào `import-mcp/source` và kéo về những gì chúng cần. Sau đó gọi công cụ `validate` với `workspace_root` đặt thành `import-mcp/source` và `release` đặt thành `release.yaml`, và công cụ `build` với `workspace_root` đặt thành `import-mcp/source`, `release` đặt thành `release.yaml` và `write` đặt thành true. Cho tôi biết bản build đã ghi những tệp nào; chúng nằm dưới `import-mcp/source/dist/`.Mở trong VS Code
Khi đã cài tiện ích mở rộng Aggrega cho Visual Studio Code, hãy mở thư mục import-mcp/source trong VS Code, nơi lần nhập đã ghi các bản nháp. Thư mục chứa một Release, chính là release.yaml đã soạn nháp, nên trình soạn thảo chọn nó cho bạn, và kiểm tra các bản nháp đối chiếu với Release đó khi bạn chỉnh sửa, đánh dấu những gì nó tìm thấy trong tệp và trong bảng Problems. Aggrega: Show topology graph, trong Command Palette, vẽ các thành phần của Release và các kết nối giữa chúng. Aggrega: Build, Aggrega: Preview build và Aggrega: Pull hoạt động trên cùng Release đó, và mỗi lệnh cũng là một nút trên bảng Commands của chế độ xem Aggrega trong thanh hoạt động; Build ghi các tệp của nó vào dist/ của thư mục. Dùng Aggrega trong Visual Studio Code trình bày phần còn lại.
Chạy thử
Không có gì trong bản build ghi Secret github-mcp-token, nên hãy tạo nó trước khi áp dụng các tệp. Ghi token của bạn vào github-token.env, dưới dạng một dòng duy nhất GITHUB_PERSONAL_ACCESS_TOKEN=<your token>, và tạo Secret từ tệp đó. Khi đó cụm đã giữ token, nên hãy xóa tệp:
kubectl create secret generic github-mcp-token --from-env-file=github-token.envrm github-token.envsecret/github-mcp-token createdÁp dụng bản build, như bước chạy của Cách một lần nhập diễn ra giải thích, và chờ hai máy chủ:
kubectl apply -R -f dist/helm/kubectl wait --for=condition=Available deployment.apps/fetch deployment.apps/github --timeout=5mservice/docs-search createdservice/fetch-default createddeployment.apps/fetch createdservice/github-default createddeployment.apps/github createddeployment.apps/fetch condition metdeployment.apps/github condition metTrên Docker Compose, trong một workspace được nhập với --target compose và đã build, hãy khởi động stack với token của bạn trong GITHUB_TOKEN của shell, biến mà Docker Compose đọc khi stack khởi động:
docker compose -p mcp -f dist/compose/docker-compose.yaml up -d --waitKiểm thử
Cầu nối phục vụ mỗi máy chủ qua cơ chế truyền tải Streamable HTTP của MCP, tại /mcp trên cổng 8080. Yêu cầu máy chủ fetch mở một phiên bằng yêu cầu initialize của MCP, yêu cầu này không đọc token nào.
Trên Docker Compose, hãy gửi nó từ một container dùng một lần trên mạng của stack, mcp_compose, nơi tên của máy chủ là fetch:
docker run --rm --network mcp_compose curlimages/curl:8.11.1 -sS http://fetch:8080/mcp \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}': keepalive
[… omitted: the same comment, repeated while the server starts]
event: messagedata: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}Trên Kubernetes, hãy chuyển tiếp một cổng cục bộ tới Service của máy chủ, fetch-default, và để lệnh tiếp tục chạy:
kubectl port-forward svc/fetch-default 8080:8080Từ một terminal khác, gửi cùng yêu cầu đó tới cổng đã chuyển tiếp:
curl -sS http://127.0.0.1:8080/mcp \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test-it", "version": "1.0.0"}}}': keepalive
: keepalive
event: messagedata: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"mcp-fetch","version":"2026.11.11"}}}Câu trả lời nêu tên máy chủ, mcp-fetch. Việc này mất một lúc: cầu nối khởi động dòng lệnh của máy chủ, uvx mcp-server-fetch, cho mỗi phiên, và uvx trước tiên tải xuống và cài đặt các gói của máy chủ — khoảng nửa phút trên Kubernetes và khoảng một phút trên Docker Compose trong lần chạy. Các dòng : keepalive là các chú thích mà luồng gửi trong lúc đó.
Máy chủ GitHub trả lời cùng yêu cầu đó tại http://github:8080/mcp trên Docker Compose, và qua kubectl port-forward svc/github-default 8080:8080 trên Kubernetes. initialize không đọc token nào, nên nó trả lời bất kể token chứa gì; lần chạy đã dùng một token giữ chỗ:
[… omitted: the keepalive comments, sent while npx installs the server]event: messagedata: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"github-mcp-server","version":"0.6.2"}},"jsonrpc":"2.0","id":1}Dừng chuyển tiếp cổng, sau đó xóa những gì bạn đã áp dụng và Secret:
kubectl delete -R -f dist/helm/kubectl delete secret github-mcp-tokenTrên Docker Compose, hãy dừng và xóa stack:
docker compose -p mcp -f dist/compose/docker-compose.yaml down