| Vấn đề |
Thông báo lỗi |
Nguyên nhân |
Các bước khắc phục/xử lý sự cố |
Lỗi không xác định khi "Tìm nạp công cụ" |
"Không tìm nạp được thông tin chi tiết về máy chủ MCP. Vui lòng thử lại." (hoặc nút Tìm nạp công cụ không hoạt động mà không có thông báo lỗi cụ thể). |
Connected Console không thể hoàn tất yêu cầu đến điểm cuối MCP của bạn do URL không hợp lệ, máy chủ ngoại tuyến hoặc lỗi mạng. |
Hãy xác minh những thông tin sau:
- Kiểm tra kỹ để đảm bảo URL điểm cuối MCP của bạn là chính xác và sử dụng
https://.
- Đảm bảo máy chủ MCP của bạn đang chạy.
- Xác nhận rằng máy chủ MCP của bạn có thể truy cập được từ Internet công cộng (Google không thể truy cập vào
localhost hoặc địa chỉ mạng nội bộ riêng tư).
|
Không thể truy cập vào máy chủ MCP |
"Không thể truy cập vào máy chủ MCP" |
Phần phụ trợ của Google không thể thiết lập kết nối với điểm cuối MCP của bạn. |
Sau đây là một số nguyên nhân và cách khắc phục phổ biến:
- Các quy định hạn chế của tường lửa: Đảm bảo tường lửa hoặc WAF của bạn không chặn dải IP gửi đi của Google.
- Quy tắc cổng API: Xác minh rằng cổng API của bạn chấp nhận các yêu cầu
POST và không từ chối clientInfo của Google trong quá trình bắt tay MCP initialize.
- Miền con không khớp: Nếu bạn sử dụng một miền con chuyên biệt (chẳng hạn như
gemini.mcp.company.com), hãy đảm bảo siêu dữ liệu /.well-known/oauth-protected-resource của miền con đó khớp với miền con đó thay vì trỏ đến một miền cơ sở khác (mcp.company.com).
|
Phương thức truyền tải MCP không được hỗ trợ (HTTP 405) |
"Máy chủ MCP đã từ chối yêu cầu (HTTP 405 Phương thức không được phép). Đảm bảo URL trỏ đến một điểm cuối HTTP có thể truyền trực tuyến chấp nhận yêu cầu POST, chứ không phải điểm cuối SSE cũ." |
URL điểm cuối trỏ đến một điểm cuối HTTP+SSE cũ chỉ chấp nhận yêu cầu GET hoặc từ chối yêu cầu JSON-RPC POST. |
Cập nhật máy chủ MCP và URL điểm cuối để sử dụng giao thức truyền tải HTTP có thể truyền trực tuyến của MCP chấp nhận các yêu cầu POST cho initialize và tools/list.
|
Thiếu tệp Tài nguyên được bảo vệ bằng OAuth |
"Tệp /.well-known/oauth-protected-resource không tồn tại trên máy chủ MCP" |
Google đã cố gắng khám phá Siêu dữ liệu tài nguyên được bảo vệ theo OAuth 2.0 (RFC 9728) nhưng không thành công. |
- Nếu máy chủ MCP của bạn KHÔNG yêu cầu xác thực: Lỗi này thường xảy ra khi URL điểm cuối MCP có lỗi chính tả hoặc thiếu phân đoạn đường dẫn (ví dụ:
https://mcp.example.com thay vì https://mcp.example.com/mcp) và trả về HTTP 404 hoặc 500, khiến ứng dụng quay lại quy trình khám phá OAuth. Xác minh rằng đường dẫn chính xác của điểm cuối MCP trả về HTTP 200 OK cho các yêu cầu initialize và tools/list POST chưa được xác thực, rồi chọn Không trong phần Máy chủ của bạn có yêu cầu uỷ quyền không? trong Thông tin đăng nhập truy cập.
- Nếu máy chủ MCP của bạn yêu cầu xác thực: Hãy lưu trữ một tệp JSON
/.well-known/oauth-protected-resource hợp lệ trên máy chủ MCP để quảng cáo các máy chủ uỷ quyền đáng tin cậy của bạn trong mảng authorization_servers.
|
Thiếu hoặc không hợp lệ siêu dữ liệu của Máy chủ uỷ quyền OAuth |
"Tệp /.well-known/oauth-authorization-server không tồn tại trên máy chủ OAuth" hoặc "chứa một JSON không hợp lệ hoặc không hoàn chỉnh" |
Máy chủ OAuth của bạn không hiển thị tài liệu siêu dữ liệu RFC 8414 hợp lệ tại /.well-known/oauth-authorization-server. |
- Lưu trữ tài liệu khám phá RFC 8414 hợp lệ tại
/.well-known/oauth-authorization-server (hoặc /.well-known/openid-configuration) chứa authorization_endpoint và token_endpoint.
- Ngoài ra, trong phần Thông tin đăng nhập, hãy nhập URL Điểm cuối uỷ quyền tuỳ chỉnh và Điểm cuối mã thông báo tuỳ chỉnh theo cách thủ công.
|
Không xác minh được miền |
Chứng chỉ miền cho thấy trạng thái "Không xác minh được" hoặc "Xác minh không thành công" kèm theo thông báo chú thích (chẳng hạn như HTTP 404, không cho phép chuyển hướng hoặc mã thông báo không khớp). |
Google không xác minh được mã xác thực của bạn tại https://<domain>/.well-known/google-connected-apps. |
- Không tìm thấy tệp (HTTP 404): Đảm bảo nội dung
google-connected-apps.json đã tải xuống được xuất bản tại https://<domain>/.well-known/google-connected-apps (không có đuôi .json trong đường dẫn URL).
- Không cho phép chuyển hướng: Phân phát trực tiếp tải trọng xác minh bằng
HTTP 200 OK; không chuyển hướng /.well-known/google-connected-apps đến một URL khác.
- Mã thông báo không khớp: Xác nhận rằng phản hồi JSON chứa
"verification_tokens": ["<YOUR_TOKEN>"] có mã thông báo chính xác được tạo cho tài khoản nhà phát triển của bạn.
|
Lỗi Đăng ký ứng dụng khách linh động (DCR) hoặc CIMD |
"Không đăng ký được ứng dụng khách linh động (RFC 7591)", "Máy chủ OAuth không hỗ trợ tính năng Đăng ký ứng dụng khách linh động (RFC 7591)" hoặc "Không đăng ký được Tài liệu siêu dữ liệu về mã ứng dụng khách (CIMD)" |
Quá trình đăng ký ứng dụng OAuth tự động không thành công hoặc không được nhà cung cấp OAuth hỗ trợ, hoặc URI chuyển hướng của Google đã bị từ chối. |
- Đảm bảo máy chủ OAuth của bạn cho phép cả 6 URI chuyển hướng của Google dành riêng cho ứng dụng, được hiển thị trong phần Thông tin xác thực máy chủ (
https://oauth-redirect.googleusercontent.com/r/<app-id>-<sanitized-domain>, v.v.). Xin lưu ý rằng nhiều máy chủ OAuth 2.1 từ chối URI chuyển hướng ký tự đại diện (*).
- Nếu nhà cung cấp OAuth của bạn không hỗ trợ CIMD hoặc RFC 7591 DCR, hãy chọn Đã đăng ký trước (đối với OAuth do người dùng uỷ quyền) hoặc Máy với máy (Thông tin đăng nhập của ứng dụng OAuth) trong phần Thông tin đăng nhập, đồng thời cung cấp Mã ứng dụng khách và Khoá bí mật của ứng dụng khách tĩnh.
|
Cửa sổ bật lên đăng nhập OAuth bị chặn hoặc trống |
"Trình duyệt đã chặn cửa sổ bật lên dùng để xác thực" hoặc cửa sổ đăng nhập OAuth không hiển thị đúng cách trong quá trình đồng bộ hoá hoặc kiểm thử công cụ. |
Trình chặn cửa sổ bật lên của trình duyệt hoặc tiêu đề X-Frame-Options/Content-Security-Policy nghiêm ngặt trên trang đăng nhập của bạn đã ngăn chặn luồng cửa sổ bật lên. |
- Cho phép cửa sổ bật lên cho bảng điều khiển trong trình duyệt rồi thử lại.
- Trong phần Thông tin đăng nhập trong mục Xác thực bằng thông tin đăng nhập của nhà phát triển, hãy chuyển từ Xác thực qua cửa sổ bật lên sang Xác thực qua chế độ chuyển hướng (dự phòng) để quy trình xác thực mở ra ở chế độ toàn màn hình trong cùng một thẻ.
|
Thiếu hướng dẫn về máy chủ MCP |
Thông báo cảnh báo: "Máy chủ MCP của bạn không có hướng dẫn. Bạn nên thêm hướng dẫn vào giản đồ máy chủ." |
Máy chủ MCP của bạn không trả về trường instructions trong phản hồi initialize. |
- Xác định rõ ràng chỉ dẫn hệ thống khi khởi chạy máy chủ MCP (tham số
instructions trong định nghĩa máy chủ).
- Đối với các phương thức triển khai HTTP không có trạng thái hoặc tuỳ chỉnh, hãy đảm bảo trường
instructions được đưa vào tải trọng phản hồi JSON-RPC cho phương thức initialize, sau đó chọn Đồng bộ hoá lại công cụ.
|
Giới hạn kích thước tài nguyên giao diện người dùng hoặc loại MIME không được hỗ trợ |
Thẻ lỗi Vấn đề khi tìm nạp: "Tổng kích thước tài nguyên không được vượt quá 100 MB" hoặc "Loại MIME '<type>' không được hỗ trợ cho tài nguyên '<uri>'." |
Máy chủ MCP của bạn đã trả về các tài nguyên giao diện người dùng có tổng kích thước vượt quá giới hạn hoặc sử dụng loại MIME không được hỗ trợ. |
- Hãy giảm tổng kích thước của tất cả tài nguyên giao diện người dùng trong tệp kê khai mà máy chủ của bạn trả về để không vượt quá giới hạn.
- Đảm bảo tất cả tài nguyên giao diện người dùng đều sử dụng một trong các loại MIME được hỗ trợ:
text/html, text/html;profile=mcp-app, text/javascript hoặc text/css.
|
Quá trình tải biểu tượng lên bị kẹt hoặc xảy ra "Lỗi không mong muốn" |
Khi tải biểu tượng ứng dụng lên trong phần chi tiết ứng dụng, quá trình tải lên bị treo ở biểu tượng vòng quay tải hoặc hiện thông báo "Đã xảy ra lỗi không mong muốn. Vui lòng thử lại" (thường có mã 4E696748). |
Thường xảy ra do phiên trình duyệt đã cũ, tiện ích trình duyệt xung đột hoặc trạng thái xác thực được lưu vào bộ nhớ đệm. |
Hãy thử các bước sau theo thứ tự:
- Sử dụng hồ sơ trình duyệt mới: Mở một cửa sổ mới bằng hồ sơ trình duyệt mới.
- Sử dụng chế độ ẩn danh/riêng tư: Đăng nhập vào Google Connected Console trong cửa sổ duyệt web ở chế độ riêng tư rồi tải biểu tượng lên.
- Xoá bộ nhớ đệm: Xoá bộ nhớ đệm và cookie của trình duyệt trước khi thử lại, đồng thời xác minh rằng biểu tượng của bạn là tệp PNG hoặc JPEG hợp lệ có kích thước 512 px × 512 px và dưới 1 MB.
|
