Microsoft Agent Framework MCP: hosted tool chỉ đọc và kiểm lỗi
Microsoft Agent Framework MCP là cách cho một agent viết bằng Microsoft Agent Framework dùng tool từ một máy chủ Model Context Protocol. Có hai đường khác nhau: hosted MCP, nơi dịch vụ model tự gọi máy chủ MCP, và local MCP, nơi chính ứng dụng của anh em kết nối tới máy chủ. Bài này chọn đường hosted với một tool chỉ đọc, khóa danh sách tool được phép, ghi lại nguồn của từng câu trả lời và thử xem chuyện gì xảy ra khi máy chủ MCP mất kết nối. ProxyVN chạy lab với agent-framework 1.24.0 ngày 03/11/2026, có ghi rõ phần nào là mô phỏng.
Microsoft Agent Framework MCP: mục tiêu và phạm vi không lặp
Phần đầu chốt bài toán, đầu ra và những gì bài không làm.
Bài toán cụ thể
Một nhóm muốn agent nội bộ tra cứu tài liệu kỹ thuật qua một máy chủ MCP có sẵn. Agent chỉ được đọc, không được tạo, sửa hay xóa gì. Mỗi câu trả lời phải cho biết tool nào đã được gọi, với tham số gì, trả về gì. Khi máy chủ MCP không trả lời, agent phải báo lỗi rõ ràng thay vì bịa ra câu trả lời nghe hợp lý.
Yêu cầu nghe đơn giản, nhưng mỗi ý chạm tới một tham số riêng của framework. Danh sách tool được phép, chế độ duyệt, header xác thực và cách đọc kết quả đều có mặc định riêng. Bài đi qua từng tham số, có số liệu chạy thật.
Đầu ra nghiệm thu
Đầu ra gồm hai thứ. Thứ nhất là bảng phiên bản SDK và transport đã dùng, để người khác dựng lại được đúng môi trường. Thứ hai là transcript một lần gọi tool, gồm cả ca thành công, ca tool lỗi và ca máy chủ MCP không kết nối được. Transcript được ẩn khóa bí mật trước khi lưu.
Ranh giới với các bài gần
Bài không hướng dẫn AutoGen hay Copilot Studio, dù cả hai đều dùng MCP. Bài cũng không viết lại cách dựng máy chủ MCP từ đầu. Máy chủ MCP trong lab chỉ có hai tool nhỏ để làm mẫu đối chứng. Trọng tâm là phía agent: khai báo, giới hạn, đọc kết quả và xử lý lỗi.
Giới hạn của phép thử
Lab không có khóa API OpenAI hay dự án Microsoft Foundry. Một lần gọi thật tới OpenAI bằng khóa giả trả lỗi 401, đúng như dự kiến. Phần còn lại của hosted MCP chạy với một máy chủ mô phỏng Responses API trên 127.0.0.1 cổng 9501. Máy chủ này ghi lại request mà framework gửi đi và trả về phản hồi dựng theo schema công khai.
Phần local MCP thì chạy thật: một máy chủ MCP viết bằng gói mcp 2.3.0 trên cổng 9502, agent-framework kết nối bằng streamable HTTP. Mọi con số về thời gian và lỗi trong bài đều đến từ hai phép chạy này.
Ai nên đọc
Người đang dựng agent bằng Python với Microsoft Agent Framework và muốn nối thêm một máy chủ MCP có sẵn. Người phụ trách bảo mật cần biết agent gửi gì ra ngoài và ai gọi máy chủ MCP. Người đã thử hosted MCP và thấy lỗi bị nuốt mất ở đâu đó giữa đường.
Nối Microsoft Agent Framework MCP với hosted tool chỉ đọc qua model provider hỗ trợ theo docs hiện hành
Phần này giải thích hai đường hosted và local theo tài liệu chính thức.
Hosted MCP là gì
Hosted và local
Theo trang Hosted MCP Tools trên Microsoft Learn, hosted MCP là tool do dịch vụ phía model gọi. Ứng dụng chỉ khai báo địa chỉ máy chủ MCP và vài tham số. Khi model quyết định dùng tool, chính dịch vụ OpenAI hoặc Foundry mở kết nối tới máy chủ MCP, lấy danh sách tool, gọi tool và đưa kết quả vào câu trả lời.
Mã nguồn của OpenAIChatClient ghi rõ trong docstring: tool từ máy chủ MCP này được OpenAI thực thi từ xa, không chạy trong ứng dụng. Câu này quyết định gần như mọi thứ còn lại trong bài, từ chỗ đặt proxy tới cách đọc lỗi.
Local MCP là gì
Trang Local MCP Tools mô tả đường ngược lại. Ứng dụng tự kết nối tới máy chủ MCP qua MCPStdioTool hoặc MCPStreamableHTTPTool. Tool chạy trong tiến trình của ứng dụng, kết quả đi qua code của anh em trước khi tới model. MCPWebsocketTool đã bị gỡ khỏi bản Python 1.23, tài liệu khuyên chuyển sang streamable HTTP.
Vì sao bài chọn hosted cho tool chỉ đọc
Hosted MCP hợp khi máy chủ MCP là dịch vụ công khai có HTTPS, như máy chủ tài liệu của Microsoft Learn. Ứng dụng không phải giữ kết nối, không phải lo vòng lặp gọi tool. Với tool chỉ đọc, rủi ro khi để dịch vụ model tự gọi thấp hơn nhiều so với tool có quyền ghi.
Đổi lại, ứng dụng nhìn thấy ít hơn. Mọi lỗi kết nối xảy ra ở phía dịch vụ model, và ứng dụng chỉ biết qua những gì phản hồi trả về. Phần thử mất kết nối ở cuối bài cho thấy khoảng trống này lớn cỡ nào.
Máy chủ MCP phải ra được Internet
Một hệ quả dễ quên: với hosted MCP, máy chủ MCP phải truy cập được từ hạ tầng của nhà cung cấp model. Địa chỉ 127.0.0.1, mạng nội bộ hay máy chủ chỉ mở cho IP văn phòng sẽ không dùng được. Nếu tool cần đọc dữ liệu nội bộ, local MCP là lựa chọn hợp lý hơn.
Agent và client trong bản 1.24
Trong Python, agent được tạo bằng lớp Agent, nhận client, tên, chỉ dẫn và danh sách tool. Client là lớp đại diện cho dịch vụ model, như OpenAIChatClient hay FoundryChatClient. Hosted MCP tool được tạo bằng phương thức get_mcp_tool của client, không phải bằng một lớp tool riêng. Phương thức này trả về một dict cấu hình, không mở kết nối nào.
Xác định provider và SDK hỗ trợ Microsoft Agent Framework MCP ở bản chọn
Phần này khóa phiên bản và chọn client.
Bảng phiên bản lab
Thành phần |
Phiên bản |
Ghi chú |
|---|---|---|
Python |
3.12.10 |
venv riêng, Windows 10 |
agent-framework |
1.24.0 |
gói gộp, kéo theo các gói con |
agent-framework-core |
1.24.0 |
Agent, MCPStreamableHTTPTool |
agent-framework-openai |
1.18.0 |
OpenAIChatClient, get_mcp_tool |
agent-framework-foundry |
1.16.0 |
FoundryChatClient, chưa chạy |
mcp |
2.3.0 |
máy chủ MCPServer và client |
openai |
3.42.1 |
SDK gọi Responses API |
httpx |
0.28.1 |
client HTTP của openai |
Provider có tài liệu hỗ trợ
Trang Hosted MCP Tools nêu hai client Python: FoundryChatClient và OpenAIChatClient. Tab C# dùng MCPToolDefinition qua Azure AI Projects SDK, tạo agent lưu phía máy chủ. Tab Go nói hosted MCP cần hỗ trợ từ phía dịch vụ. Những client khác trong hệ sinh thái, như Ollama hay Anthropic, không có trong trang này. Mình không thử chúng nên không kết luận chúng có hỗ trợ hay không.
OpenAIChatClient dùng Responses API
OpenAIChatClient trong bản 1.18 gửi request tới đường dẫn responses. Request ghi lại từ máy chủ mô phỏng có model, stream bằng false, include reasoning.encrypted_content, input, instructions, tool_choice auto và mảng tools. Hosted MCP tool nằm trong mảng tools với type là mcp.
Điểm này quan trọng khi đặt base_url tới một gateway nội bộ. Gateway phải hiểu Responses API và chuyển nguyên khối tool type mcp. Gateway chỉ hỗ trợ Chat Completions sẽ không chạy được hosted MCP.
Gói gộp kéo theo rất nhiều gói con
Lệnh pip install agent-framework cài hơn 30 gói con, gồm a2a, anthropic, bedrock, copilotstudio, gemini, mistral, ollama, redis và nhiều gói khác. Nhiều gói con đang ở dạng beta với số phiên bản kiểu 1.0.0b261030. Với môi trường production, nên cài đúng gói cần dùng, như agent-framework-core và agent-framework-openai, rồi khóa phiên bản trong tệp requirements.
Gói mcp đã sang bản 2
Bản mcp được cài kèm là 2.3.0. Trong bản 2, FastMCP đã đổi tên thành MCPServer, nằm ở mcp.server.mcpserver. Import mcp.server.fastmcp sẽ báo ModuleNotFoundError kèm đường dẫn tới hướng dẫn chuyển đổi. Code mẫu cũ trên mạng viết cho mcp 1.x cần sửa trước khi chạy.
Khi nào chọn FoundryChatClient
FoundryChatClient nhận endpoint dự án Foundry và một credential của Azure. Trang tài liệu dùng biến môi trường FOUNDRY_PROJECT_ENDPOINT và FOUNDRY_MODEL. Nếu tổ chức đã quản lý model qua Foundry, có chính sách mạng và nhật ký tập trung ở đó, đường này hợp hơn OpenAIChatClient. Lab không có dự án Foundry nên phần này chỉ dựa trên tài liệu.
Tab C# của cùng trang còn cho thấy một khác biệt: agent được tạo và lưu phía máy chủ, với tool MCP gắn vào định nghĩa agent. Khi đó cấu hình allowed_tools nằm trong dự án Foundry, không nằm trong mã ứng dụng. Người kiểm duyệt phải xem cả hai nơi.
Kiểm phiên bản trước khi chạy lab
Trước mỗi lần chạy, in phiên bản các gói ra log. Lệnh pip list lọc theo agent, mcp, openai, httpx là đủ. Framework này ra bản mới rất nhanh, và tên tham số như approval_mode hay allowed_tools có thể đổi hành vi giữa các bản. Ghi phiên bản vào transcript giúp người đọc sau biết kết quả đúng cho bản nào.
Khai báo server endpoint, auth và tool chỉ đọc được phép trong Microsoft Agent Framework MCP
Phần này đi qua từng tham số của get_mcp_tool.
Lệnh khai báo
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(model="gpt-4o-mini") # OPENAI_API_KEY lấy từ biến môi trường
docs = client.get_mcp_tool(
name="learn_docs",
url="https://learn.microsoft.com/api/mcp",
approval_mode="never_require",
allowed_tools=["microsoft_docs_search"],
headers={"Authorization": f"Bearer {token}"},
)
agent = Agent(client=client, name="doc-agent",
instructions="Chỉ tra cứu tài liệu, luôn nêu URL nguồn.",
tools=[docs])Tên tham số lấy từ chữ ký hàm trong bản 1.18 của agent-framework-openai. URL là máy chủ MCP tài liệu mà trang Microsoft Learn dùng làm ví dụ.
Dict cấu hình thật sự được gửi
In giá trị trả về của get_mcp_tool cho kết quả sau, với giá trị token đã che bằng ba dấu sao:
{"type": "mcp", "server_label": "learn_docs",
"server_url": "https://learn.microsoft.com/api/mcp",
"headers": {"Authorization": "Bearer ***"},
"allowed_tools": ["microsoft_docs_search"],
"require_approval": "never"}Tham số name thành server_label, url thành server_url, approval_mode never_require thành require_approval never. Đây là đúng khối mà máy chủ mô phỏng nhận được trong request.
Header xác thực đi qua dịch vụ model
Khối headers nằm nguyên văn trong request gửi tới nhà cung cấp model. Máy chủ mô phỏng ghi lại cả chuỗi Bearer với giá trị thật. Nghĩa là token của máy chủ MCP được chia sẻ cho nhà cung cấp model, vì chính họ là bên gọi máy chủ MCP.
Hệ quả thực tế: chỉ dùng token có quyền đọc, phạm vi hẹp, hạn ngắn. Không dùng token cá nhân có quyền ghi vào kho mã hay hệ thống quản trị. Log của ứng dụng cũng không được in request body thô, vì body chứa token.
allowed_tools là danh sách cho phép
allowed_tools giới hạn tool nào của máy chủ MCP được model nhìn thấy. Docstring ghi: để None thì bỏ bộ lọc, truyền danh sách rỗng thì gửi nguyên danh sách rỗng. Với agent chỉ đọc, luôn liệt kê rõ tên từng tool đọc. Không để None với máy chủ có cả tool ghi.
Danh sách cho phép phải lấy từ tên tool thật của máy chủ. Trước khi khai báo, gọi tools/list một lần bằng client MCP cục bộ hoặc đọc tài liệu của máy chủ để lấy tên chính xác.
approval_mode và mặc định của provider
approval_mode nhận always_require, never_require, hoặc một dict gồm always_require_approval và never_require_approval theo tên tool. Lab thử bỏ trống tham số này: request gửi đi không có trường require_approval. Khi đó hành vi phụ thuộc mặc định của nhà cung cấp. Trang tài liệu ghi ở tab Go rằng OpenAI Responses mặc định yêu cầu duyệt mọi lần gọi.
Với tool chỉ đọc đã khóa bằng allowed_tools, đặt never_require để agent chạy trọn một lượt. Với tool có quyền ghi, giữ always_require và xử lý yêu cầu duyệt trong ứng dụng.
Tool chỉ đọc là trách nhiệm của máy chủ
MCP có chú thích readOnlyHint cho tool. Máy chủ lab đánh dấu search_docs là readOnlyHint và delete_page là destructiveHint. Nhưng đây chỉ là gợi ý do máy chủ tự khai, không phải cơ chế cấp quyền. Một máy chủ ghi sai chú thích vẫn có thể xóa dữ liệu qua tool tự nhận là chỉ đọc. Quyền thật phải nằm ở token và ở phía máy chủ.
Chạy một tool call trong Microsoft Agent Framework MCP và ghi response có provenance
Phần này là transcript ca thành công.
Máy chủ mô phỏng Responses API
Máy chủ mô phỏng viết bằng http.server của Python, nghe ở 127.0.0.1 cổng 9501. Nó ghi request vào tệp JSON, rồi trả về phản hồi gồm ba phần tử output. Phần tử một là mcp_list_tools liệt kê tool search_docs. Phần tử hai là mcp_call với tên tool, tham số và output. Phần tử ba là message chứa câu trả lời của trợ lý.
Cấu trúc ba phần tử này dựng theo các kiểu output trong SDK openai 3.42.1, không phải phản hồi chụp từ OpenAI thật. Mục đích là xem framework chuyển đổi phản hồi ra sao, không phải đo chất lượng model.
Kết quả agent.run
Gọi agent.run với câu hỏi tìm trang hosted MCP, kết quả trả về có thuộc tính text bằng câu trả lời cuối. Danh sách messages chứa ba nội dung theo thứ tự. Nội dung một có type mcp_server_tool_call, call_id mcp_1, tool_name search_docs, server_name learn_docs và arguments là chuỗi JSON của tham số. Nội dung hai có type mcp_server_tool_result, cùng call_id, output là chuỗi JSON có tiêu đề và URL trang. Nội dung ba là text.
Provenance nằm ở đâu
Provenance theo call_id
Câu trả lời cuối của model chỉ là văn bản. Nguồn gốc của nó nằm ở hai nội dung đầu: tên máy chủ, tên tool, tham số và output thô. Để có provenance, ứng dụng phải lưu cả ba nội dung, không chỉ thuộc tính text.
Cặp call_id nối lời gọi với kết quả. Một câu trả lời có thể dựa trên nhiều lần gọi tool, và call_id là cách duy nhất để biết đoạn nào lấy từ lần gọi nào.
Bản ghi transcript đề xuất
import json, datetime
def ghi_transcript(r, path):
rec = {"luc": datetime.datetime.now().isoformat(), "tra_loi": r.text, "buoc": []}
for m in r.messages:
for c in m.contents:
d = c.to_dict()
d.pop("additional_properties", None)
rec["buoc"].append(d)
with open(path, "a", encoding="utf-8") as f:
f.write(json.dumps(rec, ensure_ascii=False) + "\n")Hàm này đã chạy trong lab với kết quả của máy chủ mô phỏng. Mỗi dòng JSONL là một lượt hỏi, đủ để đối chiếu sau này.
Yêu cầu agent trích nguồn
Lưu transcript là phía máy. Phía người đọc cũng cần thấy nguồn. Chỉ dẫn của agent nên yêu cầu nêu URL lấy từ output của tool. Sau đó, một bước kiểm tra đơn giản so URL trong câu trả lời với URL trong output tool. URL xuất hiện trong câu trả lời mà không có trong output nào là dấu hiệu model tự thêm.
Không lưu khóa bí mật vào transcript
Transcript chỉ chứa nội dung tool call và kết quả, không chứa request body. Token trong headers không nằm trong to_dict của các nội dung trên. Dù vậy, nếu bật log debug của httpx hay openai, request body có token sẽ xuất hiện trong log. Tắt log debug ở production, hoặc lọc header Authorization trước khi ghi.
Kiểm mất kết nối và xác nhận giới hạn hosted so với local transport trong Microsoft Agent Framework MCP
Phần này là phép thử chính của bài.
Ca một: tool lỗi giữa chừng
Máy chủ mô phỏng trả về mcp_call với status failed, output rỗng và error là chuỗi báo kết nối bị máy chủ đóng. Đây là hình dạng phản hồi khi dịch vụ model gọi được máy chủ MCP lúc đầu nhưng lời gọi tool thất bại.
Kết quả trong agent-framework 1.24: messages chỉ còn hai nội dung, mcp_server_tool_call và text. Không có nội dung kết quả nào, và chuỗi lỗi không xuất hiện trong bất kỳ nội dung nào. Đọc mã nguồn bộ chuyển đổi phản hồi không stream thì thấy kết quả chỉ được tạo khi output khác None. Trường error bị bỏ qua.
Lỗi vẫn còn trong phản hồi thô
Lỗi bị nuốt
Chuỗi lỗi không mất hẳn. Đi qua raw_representation của kết quả, tới đối tượng phản hồi của SDK openai, phần tử mcp_call vẫn có status failed và error đầy đủ. Lab in được đúng chuỗi lỗi từ đây.
Nghĩa là ứng dụng muốn biết tool có lỗi phải tự đọc raw_representation. Cách nhận biết nhanh: có mcp_server_tool_call mà không có mcp_server_tool_result cùng call_id. Khi đó đánh dấu lượt hỏi là lỗi tool, và không tin câu trả lời văn bản của model.
Ca hai: không lấy được danh sách tool
Máy chủ mô phỏng trả HTTP 424 với thông báo không lấy được danh sách tool từ máy chủ MCP learn_docs. Mã 424 Failed Dependency và câu thông báo này dựng theo dạng lỗi mà nhiều người đã báo khi dùng hosted MCP với máy chủ không truy cập được. Mình không gọi được OpenAI thật để xác nhận nguyên văn.
Kết quả: agent.run ném ChatClientException, bọc APIStatusError của SDK openai, thông báo có mã 424 và tên máy chủ. Đây là ca dễ xử lý nhất, vì lỗi nổi lên thành exception.
Ca ba: gọi thật tới OpenAI với khóa giả
Một lần gọi thật tới api.openai.com với khóa không hợp lệ trả ChatClientException bọc AuthenticationError mã 401. Thông báo che bớt khóa thành dạng sk-lab-k cùng dãy dấu sao. Lỗi này xảy ra trước khi dịch vụ chạm tới máy chủ MCP, nên không nói gì về hosted MCP. Nó chỉ xác nhận đường đi từ ứng dụng tới OpenAI hoạt động.
Local MCP: máy chủ thật trên cổng 9502
Để so sánh, lab dựng máy chủ MCP thật bằng MCPServer của gói mcp 2.3.0, transport streamable HTTP. Agent-framework kết nối bằng MCPStreamableHTTPTool với allowed_tools chỉ có search_docs và request_timeout 5 giây. Danh sách functions sau khi kết nối chỉ có search_docs, tool delete_page bị lọc đúng.
Transcript mất kết nối ở local
Bước |
Trạng thái máy chủ |
Kết quả |
Thời gian |
|---|---|---|---|
1 |
đang chạy |
OK, JSON có query, url, server, fetched_at |
0,01 giây |
2 |
vừa bị tắt |
ToolExecutionException, Connection closed, mã -32000 |
2,04 giây |
3 |
vẫn tắt |
ToolExecutionException như trên |
0,00 giây |
4 |
đã bật lại |
ToolExecutionException như trên |
0,00 giây |
5 |
sau connect(reset=True) |
OK |
0,00 giây |
Lab chạy hai lần, kết quả các bước giống nhau.
Kết nối không tự phục hồi
Bước bốn là phát hiện đáng chú ý nhất. Máy chủ đã chạy lại bốn giây, nhưng tool vẫn báo Connection closed ngay lập tức. Framework không tự mở lại phiên. Chỉ khi gọi connect với reset bằng True thì lời gọi mới thành công.
Ứng dụng chạy lâu nên bắt ToolExecutionException, gọi connect(reset=True) một lần, rồi thử lại tool. Nếu lần thử lại vẫn lỗi, dừng và báo lỗi, không lặp vô hạn.
Thời gian chờ khi máy chủ tắt
Bước hai mất 2,04 giây trước khi báo lỗi, dù request_timeout đặt 5 giây. Khi cổng không còn tiến trình nghe, hệ điều hành từ chối kết nối khá nhanh, nên lỗi đến sớm hơn ngưỡng. Ca chậm hơn là máy chủ còn nhận kết nối nhưng không trả lời. Khi đó request_timeout mới là thứ cắt lời gọi. Lab chưa dựng ca treo này, nên chưa có số đo.
Tài liệu ghi request_timeout là số giây nguyên dương, hoặc None để dùng hành vi của client MCP. Truyền 0 hay số âm sẽ báo ValueError. Với tool tra cứu tài liệu, vài giây là đủ. Với tool chạy truy vấn nặng, nên tăng ngưỡng thay vì để lỗi giả.
Thử lại có giới hạn ở tầng ứng dụng
Hosted MCP không có cơ chế thử lại mà ứng dụng điều khiển được. Mỗi lần agent.run là một request mới tới nhà cung cấp, và nhà cung cấp tự quyết việc gọi máy chủ MCP. Muốn thử lại khi gặp lỗi 424, ứng dụng bọc agent.run trong một vòng lặp nhỏ, tối đa hai hoặc ba lần, có giãn cách tăng dần.
Đừng thử lại khi lỗi là 401 hay 403. Những lỗi này do khóa hoặc quyền, chạy lại chỉ tốn thêm request và có thể làm tài khoản bị khóa tạm. Phân loại lỗi theo mã trước, rồi mới quyết định có thử lại hay không.
Bảng so sánh hosted và local khi mất kết nối
Tiêu chí |
Hosted MCP |
Local MCP streamable HTTP |
|---|---|---|
Ai gọi máy chủ MCP |
Dịch vụ model |
Ứng dụng |
Lỗi tool giữa chừng |
Mất khỏi contents, chỉ còn ở raw_representation |
ToolExecutionException |
Không tới được máy chủ |
HTTP 424 thành ChatClientException (mô phỏng) |
Connection closed sau 2,04 giây |
Phục hồi |
Mỗi lượt run là một request mới |
Cần connect(reset=True) |
Máy chủ nội bộ |
Không dùng được |
Dùng được |
Token MCP đi qua |
Nhà cung cấp model |
Chỉ ứng dụng |
Đầu ra nghiệm thu: bảng bản SDK/transport và transcript gọi một tool với tình huống mất kết nối của Microsoft Agent Framework MCP
Phần cuối gom bộ bàn giao và vai trò của proxy.
Bộ bàn giao
Bộ bàn giao gồm bảng phiên bản ở phần ba, đoạn khai báo get_mcp_tool với allowed_tools và approval_mode rõ ràng, tệp JSONL transcript và bảng ba ca lỗi. Mỗi dòng transcript có thời điểm, câu trả lời, các bước tool và trạng thái lỗi nếu có.
Thêm một dòng ghi rõ phần nào chạy với dịch vụ thật, phần nào chạy với máy chủ mô phỏng. Người nhận cần biết để không coi kết quả mô phỏng là hành vi đã kiểm trên OpenAI.
Hàm kiểm lỗi tool cho hosted
def loi_tool_hosted(r):
calls, results = set(), set()
for m in r.messages:
for c in m.contents:
if c.type == "mcp_server_tool_call": calls.add(c.call_id)
if c.type == "mcp_server_tool_result": results.add(c.call_id)
raw = getattr(r.raw_representation, "raw_representation", r.raw_representation)
errors = {it.id: it.error for it in getattr(raw, "output", []) if it.type == "mcp_call" and it.error}
return {cid: errors.get(cid, "không có kết quả") for cid in calls - results}Hàm đã chạy với ca tool lỗi của máy chủ mô phỏng và trả đúng chuỗi lỗi theo call_id. Đường dẫn raw_representation có hai lớp trong bản 1.24, có thể đổi ở bản sau, nên giữ kiểm tra getattr.
Ngưỡng nghiệm thu
Bài đạt khi request gửi đi có allowed_tools đúng tên tool chỉ đọc và require_approval được đặt rõ. Transcript ca thành công phải có call và result cùng call_id. Ca tool lỗi phải được hàm kiểm lỗi phát hiện, ca không tới được máy chủ phải nổi lên thành exception. Với local, lần gọi sau khi máy chủ chạy lại phải thành công nhờ connect(reset=True).
Khi nào cần proxy với Microsoft Agent Framework MCP
Với hosted MCP, proxy ở phía ứng dụng chỉ ảnh hưởng chặng từ ứng dụng tới nhà cung cấp model. Chặng từ nhà cung cấp tới máy chủ MCP nằm ngoài tầm của ứng dụng. Đặt proxy cho ứng dụng không đổi IP mà máy chủ MCP nhìn thấy. Nếu máy chủ MCP lọc theo IP, phải mở cho dải IP của nhà cung cấp, không phải IP proxy.
Với local MCP, MCPStreamableHTTPTool nhận tham số http_client là một httpx.AsyncClient tự cấu hình. Đây là chỗ đặt proxy khi máy chủ MCP chỉ cho phép một IP cố định. Cú pháp URL proxy có trong bài định dạng proxy. Khi máy chủ MCP nội bộ yêu cầu IP tĩnh tại Việt Nam, anh em có thể mua proxy tĩnh Việt Nam tại trang chủ ProxyVN. Proxy không cấp quyền vào máy chủ MCP, không thay token, và không làm tool ghi thành chỉ đọc.
Agent tự động và web scraping
Agent dùng MCP để đọc web cũng phải tuân theo điều khoản và robots.txt của website nguồn như mọi công cụ thu thập khác. Vai trò hợp lệ của proxy trong thu thập dữ liệu được phân tích trong bài Web Scraping proxy là gì. Các lưu ý riêng cho agent có trong bài proxy cho AI agent tự động.
Checklist Microsoft Agent Framework MCP
Checklist MCP
- Khóa phiên bản agent-framework-core, agent-framework-openai và mcp.
- Chọn hosted chỉ khi máy chủ MCP truy cập được từ Internet.
- Liệt kê rõ allowed_tools bằng tên tool chỉ đọc.
- Đặt approval_mode rõ ràng, không dựa vào mặc định của provider.
- Dùng token MCP quyền đọc, phạm vi hẹp, vì nó đi qua nhà cung cấp model.
- Lưu transcript có call_id, tool, tham số và output.
- Kiểm call không có result, đọc lỗi từ raw_representation.
- Với local, bắt Connection closed rồi gọi connect(reset=True) một lần.
Câu hỏi thường gặp về Microsoft Agent Framework MCP
Hosted MCP và local MCP khác nhau ở đâu?
Hosted do dịch vụ model gọi máy chủ MCP, local do ứng dụng tự kết nối qua MCPStdioTool hoặc MCPStreamableHTTPTool.
Có dùng hosted MCP với máy chủ trong mạng nội bộ được không?
Không. Máy chủ phải truy cập được từ hạ tầng của nhà cung cấp model. Máy chủ nội bộ dùng local MCP.
Vì sao lỗi tool không hiện trong kết quả?
Bản 1.24 bỏ trường error của mcp_call khi chuyển sang contents. Lỗi vẫn còn trong raw_representation.
Bỏ trống approval_mode thì sao?
Request không có require_approval, hành vi theo mặc định của nhà cung cấp. OpenAI mặc định yêu cầu duyệt.
Token trong headers có an toàn không?
Token được gửi tới nhà cung cấp model vì họ gọi máy chủ MCP. Chỉ dùng token quyền đọc, hạn ngắn.
Máy chủ MCP chạy lại thì agent có tự kết nối lại không?
Với local trong lab thì không. Phải gọi connect(reset=True) rồi mới gọi tool được.
Microsoft Agent Framework MCP và những điều cần nhớ
Microsoft Agent Framework MCP có hai đường với hành vi lỗi rất khác nhau. Hosted MCP gọn nhưng giấu lỗi tool trong phản hồi thô và chia sẻ token cho nhà cung cấp model. Local MCP cho ứng dụng toàn quyền nhìn lỗi nhưng không tự kết nối lại sau khi máy chủ khởi động lại. Khóa allowed_tools, đặt approval_mode rõ, lưu transcript theo call_id. Cần IP tĩnh cho máy chủ MCP nội bộ dùng với Microsoft Agent Framework MCP, liên hệ Proxy.vn - Nhà cung cấp dịch vụ proxy chất lượng hàng đầu Việt Nam.
