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

Trước khi kết nối

• Server của bạn đang chạy và Funnel đã bật (xem trang Cài đặt).
• Lấy MCP Name (AkiMCP), MCP URL và passphrase ở mục 1 của panel (hoặc ~/.aki/mcpsv/passphrase.txt).
• Dán đoạn hướng dẫn hai dòng ở mục 3 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.

IDE local: 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, chạy offline. Dùng đúng 127.0.0.1, không dùng localhost.

• Cursor: thêm mục aki-mcp với url và header Authorization: Bearer … vào ~/.cursor/mcp.json.
• Claude Code: chạy claude mcp add --transport http aki-mcp http://127.0.0.1:9999/mcp --header "Authorization: Bearer YOUR_TOKEN".
• Codex: thêm bảng [mcp_servers.aki-mcp] với url và http_headers vào ~/.codex/config.toml.

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.

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.

Client 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 (panel gợi ý 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.

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.
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

Đã xác minh, sẵn sàng production. 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 MCP Name trong panel (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.

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.

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 — độ trễ bằng 0, offline, không tunnel. 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).

Gemini (thử nghiệm)

Chỉ gói Gemini trả phí, và không được khuyên dùng. Kết nối chạy đượ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) và đặt link của custom app là MCP URL.
2. 2Trong Advanced Settings, dán Client ID và Client secret mà akimcp in ra terminal lúc khởi động (hai dòng OAuth Client ID và OAuth Client Secret; chúng cũng nằm trong ~/.aki/mcpsv/oauth-client.json). Gemini là client duy nhất còn cần hai giá trị này.
3. 3Bỏ qua nút Copy redirect URI của Gemini: redirect đã được cho phép sẵn ở phía server.
4. 4Ở bước Continue, nhập passphrase để phê duyệ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.