From 2934cd78ce251e2995a3629e55e2c94940017666 Mon Sep 17 00:00:00 2001 From: Hana <115437281+Hana-Hasa@users.noreply.github.com> Date: Fri, 30 Oct 2026 10:46:30 +0700 Subject: [PATCH] =?UTF-8?q?[docs]=20AgentBase=20Built-in=20Tools=20?= =?UTF-8?q?=E2=80=94=20th=C3=AAm=20header=20x-code-interpreter-id=20/=20x-?= =?UTF-8?q?browser-id=20v=C3=A0o=20h=C6=B0=E1=BB=9Bng=20d=E1=BA=ABn=20k?= =?UTF-8?q?=E1=BA=BFt=20n=E1=BB=91i=20MCP=20=E2=80=94=20VI=20+=20EN?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Bước 2 (Code Interpreter & Browser, VI + EN): claude mcp add --header + headers trong config JSON, ghi rõ nguồn id - Vòng đời (VI + EN): tạo qua POST /v1/code-interpreters / POST /v1/browsers, id trả về dùng làm giá trị header - README (VI + EN): ghi chú kết nối MCP gắn với tài nguyên qua header Co-Authored-By: Claude Code --- .../agent-base/built-in-tools/README.md | 2 +- .../agent-base/built-in-tools/use-browser.md | 18 +++++++++++------ .../built-in-tools/use-code-interpreter.md | 20 ++++++++++++------- .../agent-base/built-in-tools/README.md | 2 +- .../built-in-tools/su-dung-browser.md | 18 +++++++++++------ .../su-dung-code-interpreter.md | 20 ++++++++++++------- 6 files changed, 52 insertions(+), 28 deletions(-) diff --git a/English/ai-stack/agent-base/built-in-tools/README.md b/English/ai-stack/agent-base/built-in-tools/README.md index 33875877..6d1593db 100644 --- a/English/ai-stack/agent-base/built-in-tools/README.md +++ b/English/ai-stack/agent-base/built-in-tools/README.md @@ -69,7 +69,7 @@ The endpoint is an **OAuth resource server** — your client drives the whole lo Tokens from a **Root user, IAM user, or Service Account** all work — all three issue the same kind of access token. If your agent runs headless (no browser available), attach the access token directly in your client's configuration. -See each tool's page for detailed connection instructions. +Each MCP connection is pinned to a specific resource via a header — `x-code-interpreter-id` for Code Interpreter, `x-browser-id` for Browser — see each tool's page for detailed connection instructions. --- diff --git a/English/ai-stack/agent-base/built-in-tools/use-browser.md b/English/ai-stack/agent-base/built-in-tools/use-browser.md index 1ca2d792..14c537e4 100644 --- a/English/ai-stack/agent-base/built-in-tools/use-browser.md +++ b/English/ai-stack/agent-base/built-in-tools/use-browser.md @@ -21,25 +21,31 @@ https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser ``` -**Step 2:** Add it to your MCP client configuration. Example for Claude Code: +**Step 2:** Add it to your MCP client configuration, with a header pointing to the Browser to use. Example for Claude Code: ```bash -claude mcp add --transport http browser \ - https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser +claude mcp add --transport http --scope user browser \ + "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser" \ + --header "x-browser-id: " ``` -Or for Cursor / VS Code — only `url` is needed: +Or for Cursor / VS Code — add the header to the config: ```json { "mcpServers": { "browser": { - "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser" + "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser", + "headers": { + "x-browser-id": "" + } } } } ``` +Replace `` with the `id` of the Browser you created — every call over this MCP connection goes into that exact Browser. + **Step 3:** Sign in the first time — your client runs the login flow itself (**Dynamic Client Registration**) and opens the GreenNode Portal login URL in the browser; the access token is kept and **refreshed automatically** afterwards. Tokens from a **Root user, IAM user, or Service Account** all work. --- @@ -64,7 +70,7 @@ Browser follows the same pattern as [Code Interpreter](use-code-interpreter.md): ## Driving Chrome with the automation stream -**Step 1:** Create a Browser and a session (same as Code Interpreter: create → wait for `ACTIVE` → create session). +**Step 1:** Create a Browser with the `POST /v1/browsers` API, wait for the `ACTIVE` status, then create a session — same as Code Interpreter. The `id` returned on creation is the value for the `x-browser-id` header when connecting over MCP. **Step 2:** Enable the automation stream for the session (tool / API `PUT .../sessions/{sessionId}/streams`). The stream can be toggled per session. diff --git a/English/ai-stack/agent-base/built-in-tools/use-code-interpreter.md b/English/ai-stack/agent-base/built-in-tools/use-code-interpreter.md index 58401810..d77458ca 100644 --- a/English/ai-stack/agent-base/built-in-tools/use-code-interpreter.md +++ b/English/ai-stack/agent-base/built-in-tools/use-code-interpreter.md @@ -21,25 +21,31 @@ https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code ``` -**Step 2:** Add it to your MCP client configuration. Example for Claude Code: +**Step 2:** Add it to your MCP client configuration, with a header pointing to the Code Interpreter to use. Example for Claude Code: ```bash -claude mcp add --transport http code-interpreter \ - https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code +claude mcp add --transport http --scope user code-interpreter \ + "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code" \ + --header "x-code-interpreter-id: " ``` -Or for Cursor / VS Code — only `url` is needed: +Or for Cursor / VS Code — add the header to the config: ```json { "mcpServers": { "code-interpreter": { - "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code" + "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code", + "headers": { + "x-code-interpreter-id": "" + } } } } ``` +Replace `` with the `id` of the Code Interpreter you created (see [Usage lifecycle](#usage-lifecycle)) — every call over this MCP connection goes into that exact Code Interpreter. + **Step 3:** Sign in the first time. The endpoint is an OAuth resource server: your client runs the login flow itself (**Dynamic Client Registration**) and opens the GreenNode Portal login URL in the browser. After sign-in, the access token is kept and **refreshed automatically** — no re-login every session. Tokens from a **Root user, IAM user, or Service Account** all work. If your agent runs headless (no browser available), attach the access token directly in your client's configuration. Once connected, the Code Interpreter tools appear in your agent's MCP tool list. @@ -57,8 +63,8 @@ Create Code Interpreter → wait for ACTIVE → create session → invoke tools **Step 1: Create a Code Interpreter** -1. Run the create tool (or call `POST /v1/code-interpreters` via the API). -2. The request returns immediately with status `CREATING`. +1. Call `POST /v1/code-interpreters` to create a Code Interpreter. +2. The request returns immediately with status `CREATING` and an `id` — this is the value for the `x-code-interpreter-id` header when connecting over MCP. **Step 2: Wait for the ACTIVE status** diff --git a/Vietnamese/ai-stack/agent-base/built-in-tools/README.md b/Vietnamese/ai-stack/agent-base/built-in-tools/README.md index b2e80f90..3141efc5 100644 --- a/Vietnamese/ai-stack/agent-base/built-in-tools/README.md +++ b/Vietnamese/ai-stack/agent-base/built-in-tools/README.md @@ -69,7 +69,7 @@ Endpoint là một **OAuth resource server** — client tự điều phối toà Token từ **Root user, IAM user hoặc Service Account** đều dùng được — cả ba đều cấp cùng một loại access token. Nếu agent chạy headless (không mở được trình duyệt), gắn access token trực tiếp vào cấu hình của client. -Xem hướng dẫn kết nối chi tiết trong trang từng tool. +Mỗi kết nối MCP gắn với một tài nguyên cụ thể qua header — `x-code-interpreter-id` cho Code Interpreter, `x-browser-id` cho Browser — xem hướng dẫn kết nối chi tiết trong trang từng tool. --- diff --git a/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-browser.md b/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-browser.md index 6330d1eb..f5aad50f 100644 --- a/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-browser.md +++ b/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-browser.md @@ -21,25 +21,31 @@ https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser ``` -**Bước 2:** Thêm vào cấu hình MCP client của bạn. Ví dụ với Claude Code: +**Bước 2:** Thêm vào cấu hình MCP client của bạn, kèm header chỉ định Browser sẽ dùng. Ví dụ với Claude Code: ```bash -claude mcp add --transport http browser \ - https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser +claude mcp add --transport http --scope user browser \ + "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser" \ + --header "x-browser-id: " ``` -Hoặc với Cursor / VS Code — chỉ cần `url`: +Hoặc với Cursor / VS Code — thêm header vào config: ```json { "mcpServers": { "browser": { - "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser" + "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser", + "headers": { + "x-browser-id": "" + } } } } ``` +Thay `` bằng `id` của Browser bạn đã tạo — mọi lời gọi qua kết nối MCP này đi vào đúng Browser đó. + **Bước 3:** Đăng nhập lần đầu — client tự chạy flow đăng nhập (**Dynamic Client Registration**) và mở URL login của GreenNode Portal trên trình duyệt; access token được giữ và **tự refresh** sau đó. Token từ **Root user, IAM user hoặc Service Account** đều dùng được. --- @@ -64,7 +70,7 @@ Browser dùng cùng khuôn với [Code Interpreter](su-dung-code-interpreter.md) ## Điều khiển Chrome bằng automation stream -**Bước 1:** Tạo Browser và session (giống Code Interpreter: tạo → chờ `ACTIVE` → tạo session). +**Bước 1:** Tạo Browser bằng API `POST /v1/browsers`, chờ trạng thái `ACTIVE` rồi tạo session — giống Code Interpreter. `id` trả về khi tạo là giá trị đi vào header `x-browser-id` khi kết nối MCP. **Bước 2:** Bật automation stream cho session (tool/API `PUT .../sessions/{sessionId}/streams`). Luồng này bật/tắt được cho từng session. diff --git a/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-code-interpreter.md b/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-code-interpreter.md index ffb96af0..6c05b267 100644 --- a/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-code-interpreter.md +++ b/Vietnamese/ai-stack/agent-base/built-in-tools/su-dung-code-interpreter.md @@ -21,25 +21,31 @@ https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code ``` -**Bước 2:** Thêm vào cấu hình MCP client của bạn. Ví dụ với Claude Code: +**Bước 2:** Thêm vào cấu hình MCP client của bạn, kèm header chỉ định Code Interpreter sẽ dùng. Ví dụ với Claude Code: ```bash -claude mcp add --transport http code-interpreter \ - https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code +claude mcp add --transport http --scope user code-interpreter \ + "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code" \ + --header "x-code-interpreter-id: " ``` -Hoặc với Cursor / VS Code — chỉ cần `url`: +Hoặc với Cursor / VS Code — thêm header vào config: ```json { "mcpServers": { "code-interpreter": { - "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code" + "url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code", + "headers": { + "x-code-interpreter-id": "" + } } } } ``` +Thay `` bằng `id` của Code Interpreter bạn đã tạo (xem [Vòng đời sử dụng](#vong-doi-su-dung)) — mọi lời gọi qua kết nối MCP này đi vào đúng Code Interpreter đó. + **Bước 3:** Đăng nhập lần đầu. Endpoint là một OAuth resource server: client tự chạy flow đăng nhập (**Dynamic Client Registration**) và mở URL login của GreenNode Portal trên trình duyệt. Sau khi đăng nhập, access token được giữ và **tự refresh** — không cần đăng nhập lại mỗi session. Token từ **Root user, IAM user hoặc Service Account** đều dùng được. Nếu agent chạy headless (không mở được trình duyệt), gắn access token trực tiếp vào cấu hình của client. Sau khi kết nối, các tool của Code Interpreter xuất hiện trong danh sách MCP tool của agent. @@ -57,8 +63,8 @@ Tạo Code Interpreter → chờ ACTIVE → tạo session → gọi tool → (l **Bước 1: Tạo Code Interpreter** -1. Chạy tool tạo Code Interpreter (hoặc gọi `POST /v1/code-interpreters` qua API). -2. Yêu cầu trả về ngay với trạng thái `CREATING`. +1. Gọi `POST /v1/code-interpreters` để tạo Code Interpreter. +2. Yêu cầu trả về ngay với trạng thái `CREATING`, kèm `id` — đây là giá trị đi vào header `x-code-interpreter-id` khi kết nối MCP. **Bước 2: Chờ trạng thái ACTIVE**