Cách Kết Nối MCP Server Đầu Tiên Cho Codex (2026)

- Lệnh, cờ và cú pháp config.toml dưới đây đã đối chiếu tài liệu chính thức tại learn.chatgpt.com/codex/extend/mcp lúc viết 08/2026; CLI Codex đổi nhanh hơn docs, chạy codex mcp add --help để kiểm tra bản bạn đang cài trước khi phụ thuộc.

"Kết nối MCP server" trong Codex nghĩa là gì?

MCP (Model Context Protocol) là chuẩn mở cho phép một agent gọi công cụ/dữ liệu bên ngoài qua một giao diện chung, thay vì mỗi tool một tích hợp riêng. Trong Codex, "kết nối một MCP server" nghĩa là khai báo cho Codex biết: server này chạy bằng lệnh gì (hoặc URL nào), và nó cần biến môi trường/token nào để hoạt động.

Điều cần nhớ trước tiên: Codex chỉ đóng vai MCP client - nó gọi ra các server bên ngoài, chứ không tự biến thành một MCP server để công cụ khác gọi vào. Không có tài liệu nào ghi nhận chế độ server cho Codex. Nếu bạn mới làm quen khái niệm MCP nói chung (chưa riêng Codex), xem MCP là gì và hoạt động ra sao trước rồi quay lại đây.

Ba cách thêm một server

Codex cho ba đường để thêm server, không cách nào "đúng hơn" cách nào - chọn theo thói quen làm việc của bạn:

Cả ba cùng ghi vào một nơi: config.toml. Chi tiết đầy đủ nằm ở tài liệu MCP chính thức của Codex. Phần dưới đi sâu cách CLI và cách sửa file trực tiếp - hai cách nhanh nhất nếu bạn đã quen dòng lệnh.

Cách 1 - Thêm server từ CLI (STDIO)

Lệnh trung tâm chỉ có một dạng:

codex mcp add <tên-server> -- <lệnh-khởi-chạy-server>

Ví dụ thật, lấy thẳng từ tài liệu OpenAI - server context7 (tra cứu tài liệu thư viện/framework theo phiên bản), chạy qua npx:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Mình chọn ví dụ này thay vì server thương mại của một hãng nào đó vì nó trung lập - không có bên nào "cài cắm" sản phẩm của họ làm ví dụ đầu tiên cho bạn. Đa số hướng dẫn Codex-MCP bên thứ ba lại dùng chính server của họ làm demo - vẫn chạy được, nhưng đồng nghĩa bạn đang test đúng happy-path của sản phẩm họ, chứ chưa hẳn là một baseline sạch. Nếu server cần biến môi trường (API key, token…), thêm bằng cờ --env, lặp lại cờ này cho mỗi biến:

codex mcp add my-server --env API_KEY=xxx --env REGION=us -- npx -y some-mcp-server

Thêm xong, verify bằng hai cách:

• codex mcp list - liệt kê server đã cấu hình.
• Gõ /mcp ngay trong TUI của một phiên Codex - xem server nào đang active trong phiên đó.

Nếu server không xuất hiện, gần như luôn là do gõ sai cú pháp -- (dấu gạch đôi phân tách tham số của codex mcp add với lệnh thật của server) - kiểm tra lại trước khi nghi ngờ server bị lỗi.

Cách 2 - Sửa trực tiếp config.toml

Muốn kiểm soát rõ ràng hơn, hoặc muốn version-control cấu hình MCP cùng project, sửa thẳng file. Server STDIO viết như sau:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
API_KEY = "your-value-here"

Server Streamable HTTP (remote) dùng bộ khóa khác - url thay vì command/args, ví dụ với một server Figma:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"
http_headers = { "X-Client" = "codex" }

bearer_token_env_var trỏ tới tên một biến môi trường chứa token thật - bạn set biến đó ở máy, không ghi token thẳng vào file. ~/.codex/config.toml là file global, áp dụng cho mọi project. Với project đã được đánh dấu trusted, Codex cũng đọc thêm file .codex/config.toml ngay trong thư mục project - hữu ích nếu bạn muốn commit cấu hình MCP riêng cho từng repo.

Thêm một server remote (Streamable HTTP)

Đường chắc chắn nhất cho server HTTP hiện là Desktop Settings hoặc gear menu trong IDE extension: nhập tên, chọn STDIO hoặc HTTP, dán URL. Route này được tài liệu xác nhận rõ.

Chỗ cần hedge: một số hướng dẫn bên thứ ba (không phải trang docs chính thức) đưa ra cú pháp kiểu codex mcp add <tên> --url <url> để thêm server HTTP thẳng từ CLI. Tài liệu chính thức của OpenAI tại thời điểm viết bài không xác nhận cờ --url này trong phần cú pháp CLI. Đừng giả định nó có sẵn - chạy codex mcp add --help để xem đúng bản CLI bạn đang cài có hỗ trợ hay chưa, rồi hẵng dùng. Trường hợp xấu nhất, sửa thẳng config.toml (Cách 2 ở trên) vẫn chạy được bất kể bản CLI của bạn có hỗ trợ cờ đó hay không, vì nó không phụ thuộc vào một cờ CLI cụ thể nào cả.

Vài khóa tinh chỉnh dùng chung cho cả STDIO lẫn HTTP, khai báo cùng khối [mcp_servers.<tên>]: startup_timeout_sec, tool_timeout_sec, enabled (bật/tắt server), enabled_tools/disabled_tools (allow-list/deny-list công cụ mà server đó được phép expose).

Codex vs Claude Code - cấu hình MCP không giống nhau

Trang này viết cho người dùng cả Claude Code lẫn Codex, nên đáng nói rõ: đừng mang nguyên xi thói quen từ tool này sang tool kia.

Muốn xem cụ thể cùng một server thật (GitHub) được nối vào Claude Code trông ra sao, đọc nối GitHub MCP server vào Claude Code - ví dụ chéo hai tool cụ thể, không phải lý thuyết.

Kiểm tra server đã chạy chưa

Cách nhanh nhất: gõ /mcp trong TUI để xem danh sách server đang active trong phiên hiện tại. Vài lỗi hay gặp nhất:

• Thiếu biến môi trường - server cần API_KEY nhưng bạn quên --env hoặc quên khối .env trong TOML.
• Sai command/args - gõ nhầm tên package hoặc thiếu -y khi chạy qua npx.
• Token HTTP chưa set - biến trỏ bởi bearer_token_env_var chưa được set ở máy, server báo lỗi auth dù config đúng cú pháp.

Một dòng để tách bạch cho rõ ràng: MCP server thêm công cụ mới cho Codex gọi (đọc file Figma, query database…). Lớp skill của AgentKit (agentkit.best, kit trả phí - khác OpenAI AgentKit) là một tầng khác nằm trên, đóng gói workflow/quy trình sẵn - không phải cùng một thứ với việc kết nối MCP server, và không bắt buộc phải có cái này mới dùng được cái kia.

Câu hỏi thường gặp (FAQ)

Codex là một MCP server hay chỉ là client?

Chỉ là client. Codex gọi ra các MCP server bên ngoài để lấy thêm công cụ/dữ liệu; không có tài liệu nào xác nhận Codex tự chạy như một MCP server cho công cụ khác gọi vào.

Lệnh chính xác để thêm một MCP server là gì?

codex mcp add <tên-server> -- <lệnh-khởi-chạy>, ví dụ codex mcp add context7 -- npx -y @upstash/context7-mcp. Thêm biến môi trường bằng cờ --env KEY=VALUE, lặp lại cho mỗi biến.

Codex lưu config MCP ở đâu?

Ở ~/.codex/config.toml (global, áp dụng mọi project), dưới mục [mcp_servers.<tên>]. Với project đã trusted, Codex cũng đọc thêm một file .codex/config.toml ngay trong thư mục project.

Khác gì giữa STDIO và Streamable HTTP?

STDIO chạy server như một tiến trình cục bộ qua command/args (ví dụ chạy bằng npx). Streamable HTTP gọi một server từ xa qua url, xác thực bằng bearer_token_env_var hoặc header tùy chỉnh - không cần cài gì cục bộ.

Có thể thêm server remote thẳng từ CLI không?

Chưa xác nhận. Một số hướng dẫn bên thứ ba cho thấy cờ --url, nhưng tài liệu chính thức của Codex tại thời điểm viết không liệt kê cờ này. Cách chắc chắn hiện tại là Desktop Settings hoặc gear menu IDE; muốn kiểm tra CLI của bạn có hỗ trợ chưa, chạy codex mcp add --help.

Cấu hình MCP của Codex có giống Claude Code không?

Không. Codex dùng TOML (config.toml) và không có cờ scope tường minh; Claude Code dùng JSON (.mcp.json) với cờ -s local/project/user rõ ràng. Cùng chuẩn MCP, khác cách khai báo - đừng copy nguyên cú pháp từ tool này sang tool kia.

Kết luận

Chọn CLI khi cần thêm nhanh một server STDIO, chọn Desktop/IDE khi cần server remote HTTP mà chưa chắc CLI đã hỗ trợ cờ đó, và sửa thẳng config.toml khi muốn version-control cấu hình theo project. Muốn mở rộng Codex theo hướng khác ngoài MCP, xem thêm Codex Skills (SKILL.md) - một đường mở rộng song song, không thay thế MCP. Chưa nắm rõ Codex nói chung? Bắt đầu từ OpenAI Codex là gì.