Dev Mode trong ChatGPT: kết nối ứng dụng cục bộ

1. Developer Mode là gì (một cách nghiêm túc)

Bạn đã biết đôi chút về Dev Mode, nhưng giờ quan trọng là ghép thành bức tranh hoàn chỉnh dựa trên thực tế sử dụng.

Developer Mode trong ChatGPT là một chế độ đặc biệt cho phép nền tảng kết nối trực tiếp ứng dụng của bạn mà không cần xuất bản lên Store. Bạn nói với ChatGPT: “Đây là URL máy chủ MCP của tôi”, và ChatGPT sẽ coi nó như một công cụ bên ngoài có UI — có thể gọi các công cụ của nó, tải widget, tất cả ngay trong một cuộc trò chuyện thông thường.

Xét về kiến trúc, ở Dev Mode ChatGPT đóng vai trò là MCP‑client, còn template Next.js của bạn là MCP‑server. ChatGPT thiết lập kết nối tới /mcp, hỏi: “Bạn có thể làm gì?” (danh sách tools và resources), và trong cuộc đối thoại có thể gọi các công cụ này và hiển thị widget của bạn trong iframe.

Cần tách bạch Dev Mode và Store:

• Dev Mode — “garage” riêng của bạn: có thể phá, thử nghiệm, thay đổi sơ đồ công cụ 5 phút một lần mà không phải lo người dùng.
• Store — “mặt tiền” trưng bày: chỉ đưa bản ổn định sau khi review, có chính sách, mô tả, v.v. Chúng ta sẽ tới đó ở cuối khóa học, còn bây giờ chơi trong garage.

Tính đến cuối năm 2025, Dev Mode với Apps SDK khả dụng trên tất cả các gói của ChatGPT, nhưng trong tài khoản doanh nghiệp đôi khi cần quản trị viên bật nó ở cấp workspace. Nếu trong cài đặt bạn không thấy công tắc Developer Mode, đây là mục cần kiểm tra đầu tiên.

2. Những gì chúng ta đã có trước khi bắt đầu bài

Trước khi bấm gì đó trong giao diện ChatGPT, hãy đảm bảo phần cục bộ đã sẵn sàng.

Đầu tiên là dev‑server của Next.js. Ở thư mục gốc dự án, bạn đã chạy:

npm run dev

Mặc định Next.js 16 lắng nghe cổng 3000, nên UI của bạn truy cập tại http://localhost:3000.

Tiếp theo là route MCP. Trong template CodeGym Labs, máy chủ MCP được hiện thực như một route‑handler app/mcp/route.ts. Chính trong file này các công cụ và tài nguyên được đăng ký; cũng chính nơi đây nhận các yêu cầu đầu tiên từ ChatGPT khi kết nối ứng dụng ở Dev Mode.

Xét theo kiến trúc, hiện mọi thứ trông như sau:

Trình duyệt của bạn ──> http://localhost:3000 (Next.js dev, UI)
                           │
                           └── /mcp (máy chủ MCP bên trong Next.js)

Hiện chưa có liên kết nào với ChatGPT — nó chạy trên đám mây, còn localhost của bạn thì nó không thấy. Cấu hình tunnel chi tiết là chủ đề của bài tiếp theo. Ở đây, để đơn giản, giả sử bạn đã có một HTTPS‑URL công khai tới /mcp (ví dụ qua ngrok hoặc Cloudflare Tunnel, cấu hình theo README của template).

Nếu bạn chưa dựng tunnel — cũng không sao. Bây giờ bạn sẽ đi qua toàn bộ chuỗi bước trong Dev Mode để hiểu chính xác cần làm gì khi bạn có HTTPS‑URL.

Nếu bạn đã có HTTPS‑URL tới /mcp, hãy thực hiện lại mọi bước bằng tay.
Nếu chưa có — hãy xem bài như một “tour giao diện”: quan trọng là hiểu chuỗi bước; còn chạy thật chúng ta sẽ làm ở bài sau khi cấu hình tunnel.

3. Bật Developer Mode trong giao diện ChatGPT

Bước đầu tiên — chỉ cần bật hiển thị phần cài đặt cần thiết trong ChatGPT. Hãy làm như sau:

Đầu tiên truy cập phiên bản web của ChatGPT với tài khoản bạn sẽ dùng để phát triển. Nhấn vào biểu tượng hồ sơ ở góc dưới bên trái (hoặc trên bên phải — UI liên tục thay đổi) và chọn Settings (Cài đặt).

Trong cài đặt, tìm phần liên quan đến ứng dụng: thường được gọi là Apps & Connectors hoặc Connected apps. Mở phần đó. Ở cuối trang (hoặc trong thẻ Advanced / Nâng cao) sẽ có công tắc Developer Mode. Đây chính là thứ bạn cần bật.

Sau khi kích hoạt Dev Mode, ChatGPT thường hiển thị thông báo rằng chế độ nhà phát triển đã bật. Ở cùng phần đó xuất hiện nút kiểu Create, Create connector, New app — từ ngữ có thể thay đổi đôi chút, nhưng ý là: đã có cách tạo ứng dụng kết nối riêng của bạn.

Nếu trong cài đặt không hề có Apps & Connectors, cũng không có công tắc Developer Mode, hãy kiểm tra:

• bạn đã đăng nhập đúng tài khoản ChatGPT mà bạn định sử dụng chưa;
• với tài khoản doanh nghiệp, chế độ này có thể do quản trị viên bật ở cấp workspace.

Đôi khi chỉ cần đăng xuất và đăng nhập lại (phiên bản “rút phích cắm cắm lại” kinh điển cho Dev Mode).

4. Tạo ứng dụng/connector và khai báo MCP URL

Bây giờ khi Dev Mode đã bật, hãy đăng ký GiftGenius của bạn trong ChatGPT. Dưới đây là kịch bản “làm như thật”. Nếu HTTPS‑URL chưa sẵn sàng, hãy coi đây là chạy thử trước: chỉ cần xem chính xác những gì chúng ta sẽ làm khi tunnel có.

Tất cả đều thực hiện trong phần cài đặt của ChatGPT nơi bạn vừa vào. Trình tự sẽ đại khái như sau.

Mở lại Settings → Apps & Connectors. Bên trong bạn sẽ thấy danh sách ứng dụng đã kết nối (có lẽ hiện chưa có gì) và nút Create / Add connector. Nhấn vào — một form tạo ứng dụng sẽ mở ra.

Form thường có ba trường chính:

1. Tên (Name). Đây là tên dễ đọc, hiển thị với cả bạn và ChatGPT. Cho khóa học này, bạn có thể đặt, ví dụ, GiftGenius (dev) — để thấy ngay đây là bản dev cục bộ.
2. Mô tả (Description). Mô tả ngắn về ứng dụng làm gì và khi nào nên dùng. Ví dụ: “Gợi ý ý tưởng quà tặng dựa trên sở thích của người nhận”. Dòng này sau ảnh hưởng đến discovery — model dùng nó để quyết định khi nào đề xuất App của bạn trong chat.
3. URL máy chủ MCP (đôi khi ghi là Connector URL, MCP endpoint, App URL, v.v.). Đây là trường quan trọng nhất: bạn dán vào HTTPS‑URL công khai dẫn tới /mcp của ứng dụng bạn.

Ví dụ:

https://my-giftgenius-dev.ngrok.app/mcp

hoặc

https://giftgenius-dev.trycloudflare.com/mcp

Những lưu ý chính cho trường này:

• bắt buộc phải là https://, nếu không ChatGPT sẽ từ chối kết nối;
• bắt buộc có path /mcp ở cuối, vì máy chủ MCP trong template nằm ở đó; và đó cũng là path được mô tả trong tài liệu Apps SDK chính thức.

Lấy URL này ở đâu, chúng ta sẽ phân tích kỹ trong bài tiếp theo (tunnel, Cloudflare, ngrok). Giờ quan trọng là ý tưởng: http://localhost:3000/mcp cục bộ của bạn cần được “biến” thành https://…/mcp công khai, và bạn dán địa chỉ công khai đó vào form.

Sau khi điền xong, nhấn Create / Lưu. Lúc này ChatGPT sẽ “bắt tay” với máy chủ của bạn: gửi các yêu cầu HTTP tới URL đã cho, kỳ vọng nhận manifest khả năng (danh sách tools/resources, metadata) và kiểm tra máy chủ phản hồi theo giao thức MCP. Nếu mọi thứ ổn, connector sẽ xuất hiện trong danh sách, và bạn sẽ thấy các công cụ mà ChatGPT đã phát hiện. Ở phần tiếp theo, chúng ta sẽ xem chính xác điều gì xảy ra trong quá trình bắt tay này và cách xem trong log.

Nếu bạn chưa cấu hình tunnel và dán một URL giả, ChatGPT sẽ báo không thể kết nối tới máy chủ. Đây cũng là trải nghiệm hữu ích: bạn sẽ thấy lỗi hiển thị ở đâu và như thế nào.

5. Bên trong “nắp ca‑pô”: MCP‑handshake dễ hiểu

Bên ngoài trông như một form “thêm ứng dụng qua URL” bình thường. Bên trong thú vị hơn một chút, và hiểu điều này bây giờ sẽ giúp bạn gỡ lỗi dễ hơn sau này.

Bạn đã thấy khi tạo connector, ChatGPT gọi tới /mcp của bạn và kỳ vọng một manifest. Giờ hãy xem kỹ cuộc hội thoại này — điều đó cực kỳ hữu ích khi debug.

Khi nhấn nút Create, ChatGPT thực hiện vài bước.

Đầu tiên, nó gọi tới URL có /mcp, đóng vai trò MCP‑client. Theo giao thức MCP, nó kỳ vọng tại endpoint HTTP này có một server hiện thực các khả năng cơ bản: liệt kê công cụ (list tools), cung cấp tài nguyên (widget), xử lý lời gọi công cụ.

Phía server sẽ đáp lại một cấu trúc JSON mô tả:

• tên máy chủ và phiên bản;
• danh sách công cụ: name, title, description, inputSchema, v.v.;
• danh sách tài nguyên: nơi lấy HTML của widget, MIME‑type nào, render ra sao.

Trong template CodeGym cho Next.js, tất cả đã được hiện thực sẵn trong app/mcp/route.ts: ở đó dùng SDK để gọi kiểu server.registerTool(...) và server.registerResource(...).

Nếu muốn nhìn thấy quá trình bắt tay này tận mắt, bạn có thể thêm một log đơn giản vào app/mcp/route.ts. Đây là mẹo gỡ lỗi cho dev, có thể bỏ qua và quay lại sau khi muốn đào sâu:

// app/mcp/route.ts
import { NextRequest, NextResponse } from "next/server";
// nhập server / buildManifest đã tồn tại của bạn

export async function GET(req: NextRequest) {
  console.log("[MCP] Handshake from ChatGPT:", req.headers.get("user-agent"));
  const manifest = buildManifestSomehow(); // đã có sẵn trong template
  return NextResponse.json(manifest);
}

Hàm này chỉ là minh họa (cấu trúc trong template có thể khác), nhưng ý tưởng đơn giản: app/mcp/route.ts là một route‑handler Next.js bình thường, và bạn có thể log các request đến. Khi kết nối Dev Mode thành công, bạn sẽ thấy log này trong terminal nơi đang chạy npm run dev.

Về mặt giao thức, có thể vẽ thành một sơ đồ nhỏ:

sequenceDiagram
    participant ChatGPT
    participant Tunnel as HTTPS URL (/mcp)
    participant NextDev as Next.js dev + MCP

    ChatGPT->>Tunnel: Yêu cầu HTTP(S) tới https://.../mcp
    Tunnel->>NextDev: Proxy tới http://localhost:3000/mcp
    NextDev-->>Tunnel: JSON với tools và resources
    Tunnel-->>ChatGPT: Chuyển tiếp phản hồi
    ChatGPT->>ChatGPT: Cache danh sách tools/resources

Việc bạn nhập “chỉ một URL” trong form Dev Mode thực ra kích hoạt cả một cuộc trò chuyện theo giao thức.

6. ChatGPT “nhìn thấy” ứng dụng của bạn như thế nào sau khi kết nối

Giả sử bắt tay đã thành công. Vậy tiếp theo là gì?

Thứ nhất, trong phần Apps & Connectors, GiftGenius (dev) sẽ xuất hiện trong danh sách ứng dụng đã kết nối. Bên trong card, bạn sẽ thấy tên, mô tả và danh sách công cụ đã phát hiện. Ở đó thường có các nút như Refresh, Delete, v.v. Nút Refresh sẽ hữu ích sau này khi bạn thay đổi sơ đồ công cụ.

Thứ hai, ứng dụng có thể được dùng trong chính các cuộc chat. Mở một cuộc chat mới, nhấn nút “+” cạnh ô nhập. Ở đó có menu “More”, “Apps”, “Tools” — tùy phiên bản UI hiện tại. GiftGenius (dev) của bạn sẽ xuất hiện trong danh sách, và bạn có thể chọn nó cho cuộc trò chuyện này.

Sau khi chọn, ứng dụng sẽ “kết nối” với chat đó. Nhìn từ phía bạn:

• bạn viết yêu cầu tự nhiên, ví dụ: “Gợi ý quà cho fan vũ trụ với ngân sách 50$”;
• ChatGPT quyết định (dựa trên mô tả và lịch sử đối thoại) rằng có thể dùng GiftGenius, và gọi một MCP‑tool của bạn;
• kết quả có thể chứa HTML‑widget; widget được render ngay trong chat dưới dạng thẻ/bảng điều khiển.

Trong Dev Mode, bạn thường sẽ gọi ứng dụng một cách tường minh — qua menu hoặc nhắc tên ứng dụng. Nhưng cần hiểu rằng ở production, ChatGPT có thể tự “đề xuất” App của bạn, dựa vào mô tả và metadata của công cụ.

Để dễ hình dung, hãy xem bảng sau:

7. Chu kỳ phát triển: đổi code → thấy trong ChatGPT

Kết nối App — là nửa chặng đường. Nửa còn lại — hiểu cách sống cùng Dev Mode trong công việc hằng ngày.

Có hai loại thay đổi lớn: thay đổi UI (widget) và thay đổi logic/công cụ MCP.

Nếu bạn chỉ đổi UI, ví dụ chỉnh tiêu đề hoặc style trong app/page.tsx, thì với Next.js đây là frontend bình thường. Dev‑server sẽ reload module và trong trình duyệt bạn thấy hot reload. Trong ChatGPT, UI của bạn được mở trong iframe, nhưng hành vi tương tự: ở lần gọi công cụ tiếp theo render widget đó, ChatGPT sẽ tải HTML đã cập nhật. Thỉnh thoảng HMR đi thẳng vào iframe, đôi khi chỉ cần gọi lại công cụ trong chat. BỘ ĐỆM (CACHE)

Hãy thử thay đổi nhẹ widget để kiểm chứng. Giả sử trong app/page.tsx bạn có:

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius</h1>
      <p>Ở đây sẽ có phần gợi ý quà tặng.</p>
    </main>
  );
}

Đổi tiêu đề và văn bản:

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius (dev)</h1>
      <p>Phiên bản này chạy trong Dev Mode. Không dùng cho quà “production”.</p>
    </main>
  );
}

Lưu file, quay lại chat có GiftGenius đã kết nối và gọi lại ứng dụng (ví dụ bằng yêu cầu về quà tặng khi nãy). Bạn sẽ thấy tiêu đề cập nhật bên trong widget — đó là dấu hiệu tốt cho thấy chuỗi Next.js → tunnel → ChatGPT đang hoạt động.

Còn nếu bạn thay đổi phần MCP — thêm công cụ mới, đổi sơ đồ inputSchema, đổi tên tool — thì lúc này bộ nhớ đệm của ChatGPT tham gia. Ở lần kết nối đầu tiên, ChatGPT lưu danh sách công cụ và không phải lúc nào cũng tự động nhận thay đổi. Khi đó, hãy quay lại Apps & Connectors, chọn GiftGenius (dev) và nhấn kiểu Refresh schema / Refresh. Sau đó ChatGPT sẽ hỏi lại /mcp của bạn và cập nhật danh sách tool.

Nhỏ nhưng dễ “dính”: bạn đã sửa code công cụ, nhưng ChatGPT vẫn không thấy tham số mới.

8. Thực hành mini: kịch bản GiftGenius đầu tiên trong Dev Mode

Hãy ghép tất cả thành một kịch bản thực tế. Ở đây mình giả định bạn đã có một HTTPS‑URL hoạt động cho /mcp (qua tunnel hoặc deploy). Nếu chưa — chỉ cần đọc, ở bài sau bạn sẽ lặp lại với URL thật.

1. Đảm bảo npm run dev đang chạy và không có lỗi trong log. Tuyệt nhất là thấy dòng kiểu “MCP server running at http://localhost:3000/mcp” trong terminal, nếu template có log.
2. Mở ChatGPT, bật Developer Mode qua Settings → Apps & Connectors → Advanced settings.
3. Tạo connector mới GiftGenius (dev) với mô tả ngắn (“Helper for choosing gifts”) và URL dạng https://<your-domain>/mcp.
4. Đảm bảo ChatGPT đã kết nối được: trong danh sách ứng dụng bạn sẽ thấy mục mới. Nếu không kết nối — xem log của dev‑server và tunnel, đó đã là thông tin hữu ích.
5. Mở chat mới, nhấn “+”, chọn GiftGenius (dev), rồi đưa ra yêu cầu: “Gợi ý quà cho developer thích vũ trụ và cà phê, ngân sách 40$”.
6. Xem template hiện tại làm gì: ở dạng cơ bản nó có thể hiển thị một thẻ/widget đơn giản. Đây chưa phải “chọn quà thông minh”, nhưng việc có thứ gì đó xuất hiện trong chat từ code của bạn — đã là một bước tiến lớn.

Bài tập thêm: tạo một công cụ test trong MCP‑server chỉ để kiểm tra Dev Mode. Ví dụ (không bắt buộc làm ngay, chỉ xem ý tưởng):

// bên trong app/mcp/route.ts, cạnh các tools khác
server.registerTool(
  "ping_dev",
  {
    title: "Ping GiftGenius dev",
    description: "Kiểm tra dev‑server còn sống.",
    inputSchema: { type: "object", properties: {} },
  },
  async () => ({
    content: [{ type: "text", text: "GiftGenius dev is alive ✅" }],
    structuredContent: {},
  })
);

Chúng ta sẽ phân tích chi tiết server.registerTool trong mô‑đun về công cụ; tạm thời chỉ cần nhớ: qua MCP bạn mô tả “app của bạn có thể làm gì”, còn Dev Mode — là cách đưa cho ChatGPT một URL nơi các khả năng này được công bố.

9. Xem lỗi ở đâu và phân biệt “hỏng phía tôi” với “hỏng phía ChatGPT”

Không ai thích mất nửa giờ tìm bug “ở nửa hệ thống sai”, nên tốt nhất là hình thành thói quen nhìn đúng chỗ ngay từ đầu.

Nếu lỗi xuất hiện khi tạo connector. Nếu khi tạo connector, ChatGPT báo không thể kết nối App, trước hết hãy xem log của dev‑server của bạn và của tunnel. Nếu trong terminal chạy npm run dev hoàn toàn không có request tới /mcp — vấn đề nằm trên đường ChatGPT → tunnel. Nếu có request nhưng server trả 500 hoặc crash với lỗi trong console — vấn đề nằm ở code MCP của bạn.

Nếu connector đã tạo xong nhưng lỗi trong chat. Khi connector đã tạo, nhưng trong chat thỉnh thoảng xuất hiện banner “App unavailable / App broken”, thì gần như luôn là:

• dev‑server đã dừng (Next.js không còn lắng nghe cổng 3000);
• tunnel tắt hoặc URL đã thay đổi;
• endpoint MCP trả lỗi, timeout hoặc phản hồi quá chậm.

Riêng về UI/widget. Khi có vấn đề với UI (widget không render, màn hình trống, style lạ), hãy mở DevTools của trình duyệt. Widget được nạp trong iframe, và trong console của iframe đó bạn sẽ thấy lỗi JavaScript/React — y như một ứng dụng web bình thường.

Có kinh nghiệm, bạn sẽ “ngửi” ra mùi “lỗi tunnel” khác “lỗi Next.js” chỉ cần nhìn lỗi. Nhưng hiện giờ chỉ cần nhớ: bạn có ba điểm có thể hỏng — code của bạn, tunnel và ChatGPT, và xác suất lỗi nằm ở ChatGPT thường là thấp nhất.

Insight

Nếu bạn đang đọc phần này và chưa có tunnel trả phí, hãy mua ngay bây giờ. Dù sao thì trong vài ngày tới bạn cũng sẽ cần. Vậy hãy tiết kiệm thời gian và công sức cho mình.

10. Lỗi thường gặp khi làm việc với Dev Mode

Lỗi số 1: quên bật Developer Mode, mất nửa giờ tìm nút Create.
Đôi khi dev mở ChatGPT, vào Apps & Connectors và chẳng thấy gì thú vị. Nếu chưa bật Developer Mode thì nút tạo connector có thể không xuất hiện. Luôn bắt đầu bằng việc kiểm tra Dev Mode đã bật trong Advanced settings chưa, đặc biệt trên tài khoản mới hoặc trong trình duyệt khác.

Lỗi số 2: dán URL không có /mcp hoặc không phải MCP‑endpoint.
Kinh điển: trong trường URL dán https://myapp-dev.ngrok.app mà không có path /mcp, hoặc thậm chí là URL landing/servis khác. ChatGPT lịch sự gõ vào đó theo giao thức MCP, không thấy interface mong đợi và trả lỗi kết nối. Template Next.js starter nói rất rõ: phải kết nối tới URL trỏ vào /mcp — và đó là URL cần khai báo trong Dev Mode.

Lỗi số 3: cố dùng trực tiếp http://localhost:3000/mcp.
Theo trực giác, bạn muốn dán http://localhost:3000/mcp thấy trong log dev‑server. Nhưng ChatGPT chạy trên đám mây, không ở máy của bạn, và không truy cập được localhost của bạn. Ngoài ra ChatGPT yêu cầu HTTPS. Vì vậy nếu không có tunnel hay deploy từ xa, sẽ không làm được. Đây không phải bug của ChatGPT, mà là cách ly mạng bình thường.

Lỗi số 4: quên Refresh sau khi đổi sơ đồ MCP.
Sau khi bắt tay thành công, ChatGPT cache danh sách công cụ và metadata để khỏi gọi server mỗi lần. Nếu bạn thêm tool mới hoặc đổi inputSchema, mà ChatGPT vẫn hành xử như cũ, gần như chắc chắn cần Refresh connector trong Apps & Connectors. Nếu không, model đơn giản là không biết công cụ đã thay đổi.

Lỗi số 5: cố gỡ lỗi Dev Mode khi dev‑server không chạy.
Nghe hiển nhiên nhưng hay gặp: sinh viên cấu hình Dev Mode và tunnel từ xa, trong khi terminal đã không còn chạy npm run dev hoặc project không build được do lỗi cú pháp. Khi dev‑server cục bộ đang “nằm”, thì vô nghĩa khi đuổi theo lỗi Dev Mode. Luôn đảm bảo http://localhost:3000 chạy được trong trình duyệt của bạn trước khi kết nối ChatGPT.

Lỗi số 6: kỳ vọng Dev Mode là “một model khác hiểu hết mọi thứ”.
Đôi khi tưởng rằng khi bật Dev Mode thì model “biết” mọi thứ về ứng dụng của bạn. Thực tế Dev Mode không thay đổi bản thân model, nó chỉ cấp quyền truy cập tới máy chủ MCP và các công cụ của bạn. Nếu công cụ mô tả mơ hồ, mô tả App không rõ ràng hoặc logic server kỳ lạ, model sẽ bối rối y như bất kỳ dev nào khi mở một API tài liệu kém. Metadata và công cụ tốt — sẽ là chủ đề của các mô‑đun tiếp theo, nhưng hãy ghi nhớ điều này ngay từ bây giờ.

Lỗi số 7: dùng Dev Mode như production.
Rất dễ cám dỗ: “Ứng dụng chạy tốt trong Dev Mode rồi, đưa link cho người dùng để họ tự kết nối App bằng URL này nhé”. Vấn đề là Dev Mode không dành cho sử dụng đại trà: tunnel không ổn định, cấu hình có thể hỏng, và bản thân ChatGPT có thể thay đổi hành vi Dev Mode mà không đảm bảo tương thích ngược. Với người dùng thật, hãy dùng Store và deploy production. Dev Mode — chỉ là phòng thí nghiệm của bạn.