Kết nối

Kết nối app AI với Aki MCP Server

Chọn app của bạn bên dưới. Mọi AI web đăng nhập bằng OAuth đều tự đăng ký nên không có Client ID hay Secret để dán; ChatGPT cần bật Developer mode trước, còn Notion cần bật custom MCP server. Buda thì nhận access token trong header. AI khác đăng nhập bằng OAuth cũng kết nối được sau khi bạn thêm địa chỉ đăng nhập của nó trong panel. Claude và Grok đáng tin cậy nhất hiện nay; Gemini đang thử nghiệm và không được khuyên dùng.

Gặp từ chưa biết? Những từ bạn sẽ gặp

Bạn dùng loại app AI nào?

App AI trên máy này

Cursor, Claude Code, app Claude, Postman, AGY, Codex, hay bất kỳ app nào nhận MCP JSON. Chúng kết nối thẳng tới máy này qua 127.0.0.1 hoặc stdio: không cần địa chỉ công khai, không cần passphrase. Nhảy tới mục nêu tên app của bạn bên dưới.

App AI trên web

Claude.ai, ChatGPT, Grok, Notion, ClickUp, Buda, Gemini, hay AI khác đăng nhập bằng OAuth. Chúng tới máy bạn qua một địa chỉ HTTPS công khai, nên hãy bật một địa chỉ trước (xem trang Bắt đầu), rồi đăng nhập bằng passphrase. Buda thì nhận access token trong header.

Chat web không có mục connector

Nếu chat gửi được request HTTP (sandbox chạy code, công cụ fetch, Postman agent), nó kết nối bằng một token tạm thời thay vì đăng nhập. Nhảy tới mục bên dưới.

Trước khi kết nối

  • Server của bạn đang chạy (xem trang Bắt đầu). Với app AI trên web, địa chỉ công khai cũng đã bật.
  • Lấy Display name (AkiMCP nếu bạn chưa đổi tên), MCP URL và passphrase ở mục “Connectors” của panel (hoặc ~/.aki/mcpsv/passphrase.txt).
  • Dán đoạn hướng dẫn hai dòng ở mục “Instructions” của panel vào AI của bạn một lần. Nó cố định, nên không bao giờ phải dán lại.

Công cụ lập trình trên máy: Cursor, Claude Code, Codex

Các client này chạy cùng máy, nên kết nối thẳng tới http://127.0.0.1:9999/mcp bằng access token dùng chung lấy từ panel. Không tunnel, và kết nối tới AkiMCP không cần internet. Dùng đúng 127.0.0.1, không dùng localhost.

  • Cursor: bấm Apply to Cursor ở tab Cursor của panel. Nó ghi ~/.cursor/mcp.json với token hiện tại và giữ nguyên các server khác của bạn; sau khi Roll token, bấm Apply lại.
  • Claude Code: bấm Apply to Claude Code ở tab Claude Code & app của panel. Nó đăng ký server cho mọi dự án với token hiện tại, thay mục cũ nếu có; sau khi Roll token, bấm Apply lại.
  • Codex: bấm Apply ở tab Codex của panel. Nó thay ngay tại chỗ bảng [mcp_servers.akimcp] trong ~/.codex/config.toml và xóa bảng aki-mcp cũ; sau khi Roll token, bấm Apply lại.
  • Từ máy tính khác: các tab Cursor, Claude Code và Codex đều có khối From another computer với snippet dùng địa chỉ công khai cộng /mcp và token Bearer. Token được lưu dạng văn bản thường trên máy đó, và sau khi Roll token bạn dán snippet mới vào đó. Chưa được kiểm tra trên máy tính thứ hai thật. Nếu dán snippet bằng tay, hãy xóa mục aki-mcp hoặc aki-mcp-sv cũ; khóa server nay là akimcp, nên tên tool của Claude Code là mcp__akimcp__*, và danh sách cho phép ghi mcp__aki-mcp__* phải đổi tên.

Mỗi tab trong nhóm Local của panel hiển thị sẵn đoạn cấu hình đã điền token của bạn.

App khác nhận MCP JSON

Phần lớn app có màn hình cài MCP nhận cùng một đoạn JSON: một entry mcpServers có URL và header. Panel để sẵn nó trong một tab.

  1. 1Trong nhóm Local · direct của panel, mở Any MCP app (tab đầu tiên) và bấm vào JSON để sao chép. Nó trỏ tới http://127.0.0.1:9999/mcp kèm access token của bạn.
  2. 2Dán nó vào chỗ app của bạn thêm MCP server, giữ nguyên các server đã có.
  3. 3Với app trên máy khác, sao chép đoạn JSON thứ hai: nó dùng địa chỉ công khai ở mục 0, và token của nó nằm ở dạng văn bản thường trên máy đó cho tới lần Roll token kế tiếp.

Postman và Cursor dùng được đoạn JSON này ngay; tab riêng của chúng có thêm Launch cho Postman và Apply cho Cursor. Sau khi Roll token, sao chép lại JSON.

AGY (Antigravity) CLI và IDE

AGY kết nối như một lệnh stdio, nên không có URL và không có token để dán. Panel cài giúp bạn.

  1. 1Ở tab AGY của panel, bấm Apply to AGY CLI.
  2. 2Nó đăng ký akimcp trong ~/.gemini/config/mcp_config.json và cho phép sẵn mcp(akimcp/*) trong ~/.gemini/antigravity-cli/settings.json, nên CLI thôi hỏi từng tool. Nó gộp vào cấu hình sẵn có và chạy lại được an toàn.
  3. 3Antigravity IDE đọc cùng mcp_config.json, nên cũng kết nối được. IDE giữ hộp thoại duyệt từng tool riêng.

App Claude trên máy tính

Cài riêng với Claude Code; cài cái này không kết nối cái kia. App khởi chạy AkiMCP qua stdio, không cần token, nên Roll token không ảnh hưởng gì tới nó.

  1. 1Trong app Claude, mở Settings → Developer → Edit Config.
  2. 2Gộp mục ở tab Claude Code & app của panel vào dưới mcpServers trong file claude_desktop_config.json vừa mở. Tab đã điền sẵn đường dẫn của bạn.
  3. 3Thoát hẳn app rồi mở lại.

Nếu server không khởi động, thay node bằng đường dẫn đầy đủ lấy từ which node (Windows: where node).

App tự khởi chạy bộ công cụ (stdio)

Client tự khởi chạy MCP server sẽ chạy Aki MCP qua stdin/stdout. Không cần gateway, tunnel hay token.

# Lệnh mà client sẽ khởi chạy
npx -y @akinet/akimcp --stdio

Package kèm bản ghi server.json (tên io.github.lacvietanh/akimcp) mô tả nó cho MCP Registry và nêu lệnh này.

Claude.ai web connector

Claude tự khám phá OAuth. Không cần Client ID hay Client Secret.

  1. 1Vào claude.ai → Settings → Connectors → Add custom connector.
  2. 2Nhập Name (Display name trong panel, mặc định AkiMCP) và Remote MCP server URL: https://your-machine.ts.net/mcp, rồi kết nối.
  3. 3Nhập passphrase khi Aki MCP mở trang xác nhận.

Connector thuộc về tài khoản Claude của bạn: claude.ai, app Claude và app di động đều gọi tới nó từ cloud của Anthropic, nên nó cần ingress công khai kể cả trên chính máy đang chạy AkiMCP. Trên máy đó, Claude Code và app Claude có thể kết nối cục bộ thay thế, không cần ingress.

ChatGPT web và mobile

Cần gói ChatGPT có Developer mode (Plus, Pro, Business, Enterprise hoặc Edu). ChatGPT tự đăng ký nên không có Client ID để dán.

  1. 1Bật Developer mode trước, trong ChatGPT → Settings → Security and login. OpenAI yêu cầu bước này để tạo custom MCP app.
  2. 2Tạo connector trong Settings → Connectors. Nhập Name và Description tùy bạn; Icon không bắt buộc (tab ChatGPT của panel có nút Download icon tải icon AkiMCP).
  3. 3Ở mục Connection, đặt Server URL là MCP URL lấy từ panel.
  4. 4Tick I understand and want to continue, rồi bấm Create.
  5. 5Khi kết nối, nhập passphrase.

Tool chỉ-đọc chạy không cần xác nhận, còn tool nào có thể ghi vẫn hỏi. ChatGPT cho phép tool ghi nào còn tùy chính sách hiện hành của OpenAI.

Grok

Grok tự đăng ký (DCR với PKCE) nên chỉ cần dán URL.

  1. 1Mở grok.com/connectors → New Connector → Custom.
  2. 2Đặt Name trùng chính xác với Display name trong panel (mặc định AkiMCP): đoạn hướng dẫn đã dán dựa vào tên này. Đặt Server URL là MCP URL.
  3. 3Nhấn Connect và nhập passphrase để phê duyệt.

Nếu Grok cập nhật đổi địa chỉ đăng nhập và kết nối bị từ chối, địa chỉ mới sẽ hiện trong tab Other AI (sign-in) của panel, bấm một lần là thêm được.

Notion AI

Notion cần ingress công khai và workspace cho phép custom MCP server. Notion tự đăng ký nên không có gì để dán, và vẫn chạy tiếp sau khi Roll token.

  1. 1Bật custom MCP server trong cài đặt workspace Notion (có thể cần admin của workspace).
  2. 2Mở notion.so/my-connections và thêm một Custom MCP server với MCP URL lấy từ panel.
  3. 3Nhập passphrase khi Aki MCP mở trang xác nhận.
  4. 4Thêm kết nối vào trong một agent, rồi publish lại agent để agent đã publish dùng được.

Hãy kết nối Notion bằng passphrase, đừng dán access token làm bearer: bản dán đó ngừng chạy sau mỗi lần Roll token.

ClickUp

ClickUp cần một địa chỉ công khai. Nó tự đăng ký qua OAuth nên không có Client ID, secret hay token nào để dán. Sau khi Roll token, kết nối lại nó một lần từ ClickUp.

  1. 1Trong ClickUp, mở Settings → App Center → MCP Servers → Connect an MCP Server.
  2. 2Đặt Name và URL theo panel, Authentication Method = OAuth, để nguyên Advanced configuration đóng, rồi bấm Next.
  3. 3Nhập passphrase ở tab ClickUp mở ra rồi duyệt.

Sau đó ClickUp Brain tự gọi tool khi yêu cầu cần tới, không cần nhắc tên.

Buda

Buda cần ingress công khai và kết nối bằng access token dùng chung trong header, không dùng passphrase. Tab Buda của panel có sẵn mọi giá trị để copy.

  1. 1Trong Buda, mở Agent Settings → agent của bạn → Integrations → Add MCP server.
  2. 2Đặt Name theo panel, Connection type = Remote HTTP, HTTPS endpoint = MCP URL.
  3. 3Ở Authentication headers, thêm Authorization với giá trị Bearer YOUR_ACCESS_TOKEN lấy từ panel.
  4. 4Bấm Save, rồi mở chat mới để nạp tool.

Sau mỗi lần Roll token, dán lại giá trị header mới vào Buda. Cách cài này chưa được thử trên một phiên Buda thật.

Postman AI Agent

Postman chạy cùng máy, nên nó kết nối thẳng tới engine local tại http://127.0.0.1:9999/mcp, không cần tunnel hay internet cho kết nối đó. Postman không có OAuth redirect cho MCP server bên thứ ba, nên bạn dán Bearer token đã cấp thay vì vậy.

  1. 1Trong tab Postman của panel (nhóm Local), bấm vào JSON đã điền để sao chép. Nó trỏ tới URL loopback http://127.0.0.1:9999/mcp và chứa access token thật (không phải passphrase).
  2. 2Trong Postman, thêm MCP server mới tại Settings → Connected Accounts và dán JSON.
  3. 3Vẫn ở tab Postman, bấm Launch để mở Postman, rồi Send now để gửi đoạn hướng dẫn ngắn vào chat đang mở. Bật Auto-inject nếu muốn gửi vào mọi chat mới (mặc định tắt).

AI khác đăng nhập bằng OAuth?

Dành cho AI có custom connector riêng và đăng nhập bằng OAuth nhưng chưa có tab trong panel. Như mọi AI trên web, nó cần một địa chỉ công khai. Từ bản 4.2, bạn thêm địa chỉ đăng nhập của nó trong panel một lần, không cần cập nhật AkiMCP.

  1. 1Trong AI của bạn, thêm một custom connector với MCP URL lấy từ panel.
  2. 2Nếu nó không kết nối được, mở mục “Connectors” của panel → Web · needs ingress → Other AI (sign-in). Địa chỉ đăng nhập bị từ chối của nó hiện dưới Refused since AkiMCP started: bấm Add, hoặc Add as prefix để cho phép mọi địa chỉ trong thư mục đó. Địa chỉ AkiMCP không dùng được (http, localhost, địa chỉ IP) sẽ hiện lý do thay vì nút.
  3. 3Kết nối lại và nhập passphrase. Trang xác nhận ghi rõ lần đăng nhập quay về đâu, hãy kiểm tra địa chỉ đó trước khi phê duyệt.

Nếu không có địa chỉ nào bị từ chối, AI chưa hề tới được AkiMCP: hãy kiểm tra địa chỉ công khai trước (xem trang Bắt đầu). Bạn cũng có thể gõ địa chỉ vào ô ở cuối tab (chính xác, hoặc tiền tố kết thúc bằng /), hoặc ghi vào setting.json ở mục oauth.callbacks; thay đổi áp dụng ngay lần đăng nhập sau, không cần khởi động lại. Remove chặn các lần đăng nhập mới qua địa chỉ đó; muốn cắt một AI đang kết nối, dùng Revoke & roll cho nó ở mục “Security & connection limits” của panel, hoặc Roll & sign out all clients. Đã kiểm từ đầu tới cuối trên server thử nghiệm, chưa kiểm với một AI thật.

App AI của bạn không có mục connector?

Nếu chat gửi được request HTTP, chính chat trở thành MCP client bằng các request HTTP thuần: nhà cung cấp không cần hỗ trợ custom MCP. Nó đăng nhập bằng một token tạm thời thay vì passphrase.

  1. 1Trong nhóm Web · needs ingress của panel, mở tab Any HTTP chat và bấm Mint temp token & copy kickoff. Khối đó chứa link hướng dẫn, MCP URL và token.
  2. 2Dán khối đó vào chat, rồi giao việc cho nó.
  3. 3Khi xong việc, bảo chat tự thu hồi token của nó, hoặc bấm Revoke bên cạnh token trong panel.

Token sống 4 giờ; nút +30 min cạnh nó trong panel cộng thêm nửa giờ, bấm bao nhiêu lần cũng được, và Last used cho biết nó được dùng lúc nào, từ đâu. Khởi động lại server sẽ thu hồi nó; token dùng chung và các app khác vẫn chạy. Giao thức chat làm theo: hướng dẫn HTTP của AkiMCP cho chat web (v1).

Gemini (thử nghiệm)

Chỉ gói Gemini trả phí, và không được khuyên dùng. Bản 3.1 cho nó đăng nhập lại bằng passphrase (chưa kiểm trên phiên thật); ở các lần thử trước nó kết nối được nhưng dùng tool chưa ổn định.

  1. 1Mở custom connected apps của Gemini (Gemini → gói trả phí → Custom apps), dán MCP URL rồi bấm Next.
  2. 2Nhập passphrase ở trang xác nhận của AkiMCP rồi bấm Approve. Gemini tự đăng ký nên không cần dán gì thêm; Client ID/Secret cấp sẵn mà akimcp in ra lúc khởi động chỉ là phương án dự phòng.
  3. 3Bỏ qua nút Copy redirect URI của Gemini: các địa chỉ chuyển hướng của Google đã được cho phép sẵn ở phía server. Luồng này chưa được thử trên một phiên Gemini thật.

Qua nhiều lần thử, Gemini chấp nhận kết nối nhưng không phát hiện/điều khiển tool ổn định. Hãy ưu tiên Claude, Grok hoặc ChatGPT lúc này.

Chạy AkiMCP trên nhiều máy? Đặt tên cho từng máy

Tùy chọn, từ bản 4.0. Một tên riêng giúp app AI liệt kê từng máy tách bạch. Giữ tên mặc định AkiMCP thì bỏ qua mục này.

  1. 1Ở đầu mục Connectors của panel, gõ Display name. Server ID và Tool prefix tự theo khi bạn gõ: MacMCP cho macmcp và mac__run_cmd. Customize fields để tự đặt từng mục.
  2. 2Bấm Save name, rồi khởi động lại AkiMCP.
  3. 3Kết nối lại ở mọi app. Ở Claude Code, Codex, Cursor và AGY, bấm Apply: nó chuyển entry sang Server ID mới. Ở app web, gõ Display name mới làm tên connector. Claude sẽ hỏi Always allow lại cho từng tool.

Hãy đặt lại tên mặc định (Reset to AkiMCP) trước khi cài một bản 3.x. AIObox chỉ tự kết nối claude.ai khi tên có chứa AkiMCP. Việc đổi tên mới được kiểm bằng cách đọc code, chưa kiểm với client thật.