Model Context Protocol
Model Context Protocol
Cấp cho Codex quyền truy cập vào các công cụ và ngữ cảnh của bên thứ ba
Model Context Protocol (MCP) kết nối các mô hình với công cụ và ngữ cảnh. Hãy dùng giao thức này để cấp cho ChatGPT hoặc Codex quyền truy cập vào tài liệu của bên thứ ba, hoặc để cho phép chúng tương tác với các công cụ dành cho nhà phát triển như trình duyệt hay Figma của bạn.
ChatGPT web có thể sử dụng các công cụ từ xa dựa trên MCP do plugin cung cấp. Sau khi cài đặt plugin, Chat và Work có thể sử dụng các trình kết nối và công cụ MCP từ xa đi kèm với plugin đó. Mở thẻ Plugins để duyệt và quản lý các công cụ khả dụng. Các ứng dụng Codex cục bộ cũng có thể kết nối trực tiếp với máy chủ MCP và chia sẻ cấu hình của chúng.
Ứng dụng ChatGPT dành cho máy tính, Codex CLI và tiện ích mở rộng IDE hỗ trợ máy chủ MCP và dùng chung cấu hình MCP trên cùng một máy chủ Codex.
Các tính năng máy chủ được hỗ trợ dưới đây áp dụng cho những máy chủ MCP được cấu hình trên một máy chủ Codex. Các công cụ plugin được lưu trữ có thể có những khả năng khác.
Các tính năng MCP được hỗ trợ
- Máy chủ STDIO: Các máy chủ chạy dưới dạng tiến trình cục bộ (được khởi động bằng một lệnh).
- Biến môi trường
- Máy chủ HTTP có thể truyền phát: Các máy chủ mà bạn truy cập tại một địa chỉ.
- Xác thực bằng bearer token
- Xác thực OAuth, bao gồm Client ID Metadata Documents (CIMD) và Dynamic Client Registration (DCR)
- Xác thực bằng phiên ChatGPT cho các máy chủ bên thứ nhất đáng tin cậy
- Hướng dẫn của máy chủ: Codex đọc trường MCP
instructionsđược trả về trong quá trình khởi tạo và sử dụng trường này làm hướng dẫn áp dụng trên toàn máy chủ cùng với các công cụ của máy chủ.
Nếu bạn xây dựng hoặc duy trì một máy chủ MCP cho Codex, hãy dùng instructions cho các quy trình liên công cụ, ràng buộc và giới hạn tốc độ áp dụng trên toàn máy chủ. Hãy bảo đảm 512 ký tự đầu tiên có thể tự truyền đạt đầy đủ ý nghĩa để Codex nắm được hướng dẫn quan trọng nhất khi quyết định cách sử dụng máy chủ.
Kết nối Codex với máy chủ MCP
Codex lưu cấu hình MCP trong config.toml cùng với các thiết lập cấu hình Codex khác. Theo mặc định, vị trí này là ~/.codex/config.toml, nhưng bạn cũng có thể giới hạn phạm vi máy chủ MCP theo từng dự án bằng .codex/config.toml (chỉ dành cho dự án đáng tin cậy).
Ứng dụng ChatGPT dành cho máy tính, Codex CLI và tiện ích mở rộng IDE dùng chung cấu hình này. Sau khi cấu hình các máy chủ MCP, bạn có thể chuyển đổi giữa những ứng dụng này mà không cần thiết lập lại.
Cấu hình trong ứng dụng ChatGPT dành cho máy tính
- Mở Cài đặt, rồi chọn Máy chủ MCP.
- Chọn Thêm máy chủ.
- Nhập tên, chọn STDIO hoặc Streamable HTTP, rồi cung cấp lệnh hoặc URL của máy chủ.
- Lưu máy chủ, rồi chọn Khởi động lại.
Danh sách máy chủ cho biết máy chủ nào đang được bật và máy chủ nào yêu cầu OAuth. Chọn
Xác thực khi máy chủ OAuth yêu cầu đăng nhập. Trong ô soạn thảo, nhập /mcp
để xem các máy chủ đã kết nối.
Sử dụng các công cụ dựa trên MCP trong ChatGPT web
Trong cuộc trò chuyện ChatGPT Work được lưu trữ, hãy cài đặt một plugin để sử dụng các trình kết nối và công cụ MCP từ xa đi kèm. Sau khi cài đặt, Chat và Work có thể sử dụng các công cụ đó. Quản trị viên không gian làm việc có thể kiểm soát những plugin và công cụ nào khả dụng.
ChatGPT web không đọc các tệp cấu hình Codex cục bộ hoặc hiển thị trình đơn lệnh Codex cục bộ. Hãy mở thẻ Plugins để duyệt và quản lý các công cụ khả dụng.
Cấu hình bằng CLI
Thêm máy chủ MCP
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>Ví dụ, để thêm Context7 (một máy chủ MCP miễn phí dành cho tài liệu của nhà phát triển), bạn có thể chạy lệnh sau:
codex mcp add context7 -- npx -y @upstash/context7-mcpCác lệnh CLI khác
Chạy codex mcp list để xem các máy chủ đã cấu hình. Để xem tất cả các lệnh MCP
hiện có, hãy chạy codex mcp --help. Đối với máy chủ hỗ trợ OAuth, hãy chạy
codex mcp login <server-name>.
Giao diện người dùng trong terminal (TUI)
Trong TUI của codex, hãy dùng /mcp để xem các máy chủ MCP đang hoạt động của bạn.
Cấu hình trong tiện ích mở rộng IDE
- Mở trình đơn bánh răng, sau đó chọn Máy chủ MCP.
- Chọn Thêm máy chủ.
- Nhập tên, chọn STDIO hoặc Streamable HTTP, rồi cung cấp lệnh hoặc URL của máy chủ.
- Lưu máy chủ, sau đó chọn Khởi động lại tiện ích mở rộng.
Danh sách máy chủ MCP cho biết máy chủ nào đang được bật và máy chủ nào yêu cầu OAuth. Chọn Xác thực khi một máy chủ OAuth yêu cầu đăng nhập.
Cấu hình bằng config.toml
Để kiểm soát chi tiết hơn, hãy chỉnh sửa ~/.codex/config.toml hoặc tệp có phạm vi dự án
.codex/config.toml. Xem tài liệu tham khảo về cấu hình
để tra cứu danh sách mọi tùy chọn MCP được hỗ trợ.
Cấu hình từng máy chủ MCP bằng một bảng [mcp_servers.<server-name>] trong tệp cấu hình.
Máy chủ STDIO
command(bắt buộc): Lệnh khởi động máy chủ.args(tùy chọn): Các đối số truyền cho máy chủ.env(tùy chọn): Các biến môi trường cần thiết lập cho máy chủ.env_vars(tùy chọn): Các biến môi trường được phép chuyển tiếp.cwd(tùy chọn): Thư mục làm việc dùng để khởi động máy chủ.experimental_environment(tùy chọn): Đặt thànhremoteđể khởi động máy chủ stdio thông qua môi trường thực thi từ xa khi có sẵn.
env_vars có thể chứa tên biến dạng thuần văn bản hoặc các đối tượng có nguồn:
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]Các mục chuỗi và source = "local" đọc từ môi trường cục bộ của Codex.
source = "remote" đọc từ môi trường thực thi từ xa và yêu cầu
MCP stdio từ xa.
Máy chủ Streamable HTTP
url(bắt buộc): Địa chỉ máy chủ.auth(không bắt buộc): Phương thức xác thực sẽ thử sau các bearer token và header ủy quyền đã cấu hình. Dùngoauth(mặc định) cho thông tin xác thực MCP OAuth đã lưu. Dùngchatgptđể sử dụng phiên ChatGPT hiện tại cho origin ChatGPT chính chủ đáng tin cậy, với OAuth đã lưu làm phương án dự phòng.bearer_token_env_var(không bắt buộc): Tên biến môi trường chứa bearer token cần gửi trongAuthorization.http_headers(không bắt buộc): Ánh xạ từ tên header đến các giá trị tĩnh.env_http_headers(không bắt buộc): Ánh xạ từ tên header đến tên biến môi trường (giá trị được lấy từ môi trường).http_headers_helper(không bắt buộc): Lệnh cục bộ in ra một đối tượng JSON gồm tên header và giá trị chuỗi, chẳng hạn như{"X-Auth": "temporary-token"}. Được hỗ trợ cho các kết nối HTTP MCP được tạo từ môi trường cục bộ; không áp dụng cho máy chủ stdio hoặc các kết nối được tạo thông qua môi trường thực thi từ xa.
Codex lưu các header từ trình trợ giúp vào bộ nhớ đệm cho kết nối. Sau khi một yêu cầu POST cùng origin
trả về 401 hoặc 403, Codex làm mới các header một lần và chỉ thử lại nếu
trình trợ giúp trả về các giá trị đã thay đổi. Bearer token được chỉ định rõ ràng và thông tin xác thực OAuth
được ưu tiên hơn header Authorization do trình trợ giúp cung cấp.
Phản hồi OAuth 403 báo cáo phạm vi không đủ sẽ không kích hoạt việc
làm mới trình trợ giúp.
Nếu không phân giải được nguồn thông tin xác thực nào, Codex có thể kết nối với máy chủ mà không cần
xác thực. Chạy riêng codex mcp login <server-name> để bắt đầu quy trình đăng nhập
MCP OAuth.
Các tùy chọn cấu hình khác
startup_timeout_sec(không bắt buộc): Thời gian chờ (giây) để máy chủ khởi động. Mặc định:10.tool_timeout_sec(không bắt buộc): Thời gian chờ (giây) để máy chủ chạy một công cụ. Mặc định:60.enabled(không bắt buộc): Đặt thànhfalseđể vô hiệu hóa máy chủ mà không xóa máy chủ đó.required(không bắt buộc): Đặt thànhtrueđể quá trình khởi động thất bại nếu máy chủ đang bật này không thể khởi tạo.enabled_tools(không bắt buộc): Danh sách công cụ được phép.disabled_tools(không bắt buộc): Danh sách công cụ bị từ chối (được áp dụng sauenabled_tools).default_tools_approval_mode(không bắt buộc): Hành vi phê duyệt mặc định cho các công cụ từ máy chủ này. Các giá trị được hỗ trợ làauto,prompt,writesvàapprove. Chế độwritessẽ yêu cầu xác nhận đối với các công cụ không được đánh dấu là chỉ đọc.tools.<tool>.approval_mode(không bắt buộc): Ghi đè hành vi phê duyệt cho từng công cụ.tools.<tool>.output_token_limit(không bắt buộc): Ngân sách token dương cho đầu ra của một công cụ, trước mức dự phòng tuần tự hóa tiêu chuẩn 20%. Ghi đè ngân sách cắt bớt đầu ra mặc định của mô hình cho công cụ đó.
Cài đặt cấp cao nhất mcp_optional_startup_grace_ms kiểm soát khoảng thời gian Codex
chờ các máy chủ MCP không bắt buộc khi xây dựng danh mục công cụ ban đầu. Giá trị
mặc định là 1000 mili giây. Đặt thành 0 để chờ theo
startup_timeout_sec của từng máy chủ. Các máy chủ bắt buộc vẫn sử dụng thời gian chờ
khởi động tương ứng.
Đăng ký máy khách OAuth và URL callback
Khi máy chủ ủy quyền yêu cầu máy khách OAuth đã được đăng ký trước, hãy cung cấp ID máy khách khi thêm máy chủ MCP:
codex mcp add example --url https://mcp.example.com --oauth-client-id my-clientCodex hiển thị URL callback đầy đủ để bạn đăng ký với nhà cung cấp:
OAuth callback URL: http://127.0.0.1/callbackCodex lưu callback cùng với ID máy khách trong config.toml để dùng cho các lần
đăng nhập sau:
[mcp_servers.example]
url = "https://mcp.example.com"
[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"Các máy khách đăng ký trước mới được thêm chỉ sử dụng callback ổn định khi
máy chủ ủy quyền công bố
authorization_response_iss_parameter_supported: true và cung cấp issuer trong siêu dữ liệu.
Nếu khả năng hỗ trợ issuer không được công bố, Codex sẽ thêm một ID callback dành riêng cho máy chủ,
chẳng hạn như http://127.0.0.1/callback/XuuuHAzzHOni. Các máy khách hiện có
không có callback đã lưu sẽ tiếp tục sử dụng chuyển hướng dành riêng cho ID callback của mình.
Trong quá trình đăng nhập, việc lựa chọn callback phụ thuộc vào cấu hình OAuth và siêu dữ liệu của máy chủ ủy quyền:
| Cấu hình OAuth | Hỗ trợ issuer | Callback được sử dụng |
|---|---|---|
callback_url không có client_id |
Có hỗ trợ | Callback đã cấu hình được dùng để đăng ký máy khách. |
callback_url không có client_id |
Không hỗ trợ | Callback đã cấu hình được dùng để đăng ký máy khách và được thêm ID callback dành riêng cho máy chủ. |
client_id và callback_url |
Có hỗ trợ | Callback đã cấu hình được tái sử dụng; phản hồi ủy quyền phải chứa iss khớp. |
client_id và một callback_url kết thúc bằng ID callback chính xác |
Không hỗ trợ | Callback đã cấu hình được tái sử dụng mà không thay đổi. |
client_id và một callback_url thiếu ID callback chính xác |
Không hỗ trợ | Callback đã cấu hình bị bỏ qua. Codex sử dụng mcp_oauth_callback_url, hoặc http://127.0.0.1/callback nếu chưa đặt, rồi thêm ID callback. |
client_id không có callback_url được cấu hình |
Có hoặc không hỗ trợ | Codex sử dụng callback toàn cục hoặc mặc định rồi thêm ID callback dành riêng cho máy chủ. |
Cơ chế dự phòng không sửa đổi URL callback đã lưu. Codex suy ra ID callback từ URL của máy chủ MCP, bao gồm đường dẫn và chuỗi truy vấn. Các quy tắc lựa chọn tương tự áp dụng cho cả đăng nhập tự động và đăng nhập rõ ràng.
Đặt mcp_oauth_callback_url khi bạn cần đường dẫn callback tùy chỉnh hoặc URL ingress
Devbox từ xa. Các máy khách đăng ký trước mới được thêm sẽ sử dụng nguyên URL đó
khi nhà cung cấp hỗ trợ nhận dạng issuer. Nếu không, chúng sẽ sử dụng
URL đã cấu hình và thêm ID callback dành riêng cho máy chủ. Luôn đăng ký
callback chính xác mà codex mcp add hiển thị.
Đối với callback http://127.0.0.1 không chỉ định cổng, Codex bỏ cổng trình lắng nghe khỏi
URL được hiển thị và lưu, sau đó chèn cổng trình lắng nghe đang hoạt động trong quá trình
ủy quyền. Cơ chế thay thế này không áp dụng cho localhost, máy chủ IPv6,
URL HTTPS hoặc callback đã bao gồm cổng. Máy chủ ủy quyền
phải chấp nhận các cổng loopback thay đổi theo
RFC 8252, Mục 7.3.
Đặt mcp_oauth_callback_port để chọn một cổng trình lắng nghe toàn cục cố định, hoặc đặt
mcp_servers.<server-name>.oauth.callback_port để ghi đè cổng đó cho một máy chủ.
Một cổng được chỉ định rõ trong URL callback không cấu hình trình lắng nghe. Đối với
callback loopback trực tiếp, hãy dùng http://127.0.0.1 không chỉ định cổng hoặc cấu hình cùng một
cổng rõ ràng cho cả URL callback và trình lắng nghe. Callback qua proxy có thể
cố ý sử dụng cổng URL bên ngoài khác với cổng trình lắng nghe cục bộ.
URL callback cục bộ liên kết với giao diện cục bộ; URL callback không cục bộ
liên kết với 0.0.0.0.
Codex xác thực mọi iss được trả về trước khi trao đổi mã ủy quyền. Phản hồi
có iss không khớp luôn bị từ chối. Khi khả năng hỗ trợ issuer được công bố,
phản hồi thiếu iss cũng bị từ chối. Trong cả hai trường hợp, mã đều không được trao đổi và hệ thống không
chuyển sang callback khác. URL callback không hợp lệ hoặc khả năng hỗ trợ issuer được công bố
nhưng không có issuer trong siêu dữ liệu cũng vẫn là lỗi nghiêm trọng. Xem
Xác thực người dùng.
Nếu máy chủ MCP quảng bá scopes_supported, Codex ưu tiên các phạm vi
do máy chủ quảng bá đó khi đăng nhập OAuth. Nếu không, Codex sẽ dùng các
phạm vi được cấu hình trong config.toml.
Đăng ký ứng dụng khách OAuth
Codex hỗ trợ OAuth Client ID Metadata Documents (CIMD)
và Dynamic Client Registration (DCR). Theo mặc định, Codex tự động chọn
CIMD khi máy chủ ủy quyền công bố
client_id_metadata_document_supported: true, bao gồm none trong
token_endpoint_auth_methods_supported và lệnh gọi lại sử dụng URL
loopback được hỗ trợ. Nếu không, Codex sử dụng DCR khi có sẵn. ID ứng dụng khách OAuth
đã cấu hình luôn được ưu tiên và bỏ qua bước đăng ký ứng dụng khách.
Đối với CIMD, Codex sử dụng một tài liệu siêu dữ liệu do ChatGPT lưu trữ dành riêng cho máy chủ MCP đó:
https://chatgpt.com/oauth/codex/<callback_id>/client.jsonCodex lấy <callback_id> từ URL của máy chủ MCP và đưa giá trị này vào
URI chuyển hướng loopback, chẳng hạn như
http://127.0.0.1:<port>/callback/<callback_id>. Tài liệu siêu dữ liệu đăng ký
URI loopback tương ứng không có cổng. Máy chủ ủy quyền phải chấp nhận
cổng được chọn khi đăng nhập, đồng thời đối chiếu chính xác máy chủ và đường dẫn theo yêu cầu của
RFC 8252. Máy chủ, đường dẫn hoặc tham số truy vấn
gọi lại tùy chỉnh yêu cầu DCR hoặc một OAuth client ID đã cấu hình.
Khả năng hỗ trợ một tài liệu CIMD dùng chung, ổn định đang được phát triển và sẽ sớm ra mắt:
https://chatgpt.com/oauth/codex/client.jsonCodex sẽ sử dụng tài liệu ổn định với đường dẫn /callback dùng chung khi
máy chủ ủy quyền công bố
authorization_response_iss_parameter_supported: true, cung cấp một
issuer hợp lệ trong siêu dữ liệu và đưa một iss tương ứng vào phản hồi
ủy quyền. Các máy chủ không có phản hồi ràng buộc với bên phát hành sẽ tiếp tục sử dụng
tài liệu dành riêng cho lệnh gọi lại.
Để chọn phương thức đăng ký cho một lần đăng nhập CLI, hãy sử dụng
--oauth-client-registration:
codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcrGiá trị mặc định là auto. Lựa chọn đăng ký chỉ áp dụng cho lần đăng nhập hiện tại và
không được lưu trong config.toml.
Ví dụ về config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000Máy chủ MCP do plugin cung cấp
Các plugin đã cài đặt có thể đóng gói máy chủ MCP trong tệp kê khai plugin. Những
máy chủ này được khởi chạy từ plugin, vì vậy cấu hình người dùng không đặt lệnh
truyền tải của chúng. Cấu hình người dùng vẫn có thể kiểm soát trạng thái bật/tắt và chính sách công cụ
trong plugins.<plugin>.mcp_servers.<server>.
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]
[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"Máy chủ HTTP MCP do plugin cung cấp cũng có thể khai báo cài đặt OAuth trong .mcp.json.
Tệp kê khai plugin sử dụng các tên trường camelCase clientId, callbackUrl và
callbackPort:
{
"mcpServers": {
"sample": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "my-pre-registered-client",
"callbackUrl": "http://127.0.0.1/callback/registered"
}
}
}
}Máy chủ MCP do plugin cung cấp tuân theo các quy tắc chọn callback giống như các
máy chủ MCP khác. Nếu plugin cung cấp clientId, nhà cung cấp của plugin không hỗ trợ
callback ràng buộc với issuer và callbackUrl thiếu ID callback dành riêng cho máy chủ,
Codex sẽ bỏ qua URL đó khi đăng nhập và sử dụng mcp_oauth_callback_url, hoặc
http://127.0.0.1/callback nếu chưa đặt, rồi thêm ID callback. Giá trị
callbackUrl đã cấu hình vẫn không thay đổi.
oauth.callbackPort của plugin ghi đè giá trị toàn cục
mcp_oauth_callback_port; nếu cả hai đều chưa được đặt, Codex sẽ chọn một cổng tạm thời.
Cổng được nhúng trong callbackUrl không chọn cổng trình lắng nghe. Đối với
callback loopback trực tiếp có cổng cố định, hãy cấu hình hai giá trị sao cho khớp nhau:
{
"callbackUrl": "http://127.0.0.1:4321/callback/registered",
"callbackPort": 4321
}Đối với ingress từ xa hoặc một proxy khác, cổng URL callback và cổng trình lắng nghe cục bộ có thể được cố ý đặt khác nhau khi proxy chuyển tiếp đến trình lắng nghe đã cấu hình.
Ví dụ về các máy chủ MCP hữu ích
Danh sách máy chủ MCP không ngừng mở rộng. Dưới đây là một vài lựa chọn phổ biến:
- OpenAI Docs MCP: Tìm kiếm và đọc tài liệu dành cho nhà phát triển của OpenAI.
- Context7: Kết nối với tài liệu dành cho nhà phát triển luôn được cập nhật.
- Figma Cục bộ và Từ xa: Truy cập các thiết kế Figma của bạn.
- Playwright: Điều khiển và kiểm tra trình duyệt bằng Playwright.
- Chrome Developer Tools: Điều khiển và kiểm tra Chrome.
- Sentry: Truy cập nhật ký Sentry.
- GitHub: Quản lý GitHub ngoài những gì
githỗ trợ (ví dụ: yêu cầu kéo và vấn đề).