Động Lực & Mục Đích

Vì sao Aki MCP Server tồn tại?

Giải pháp né chi phí API tính theo token và tình trạng khóa thiết bị của app desktop.

Tận dụng quota Web/Pro rẻ thay vì trả theo token API

Gói Claude Pro / ChatGPT Plus hàng tháng rẻ hơn nhiều so với trả per-token qua API khi làm việc dự án thực tế: đọc toàn bộ mã nguồn, theo dõi log liên tục. Aki MCP Server mang sức mạnh quota Web đó thẳng vào mã nguồn local của bạn.

Linh hoạt đa tài khoản, không khóa thiết bị

Claude Desktop app khóa việc sử dụng theo Device ID và buộc bạn đăng xuất/đăng nhập lại mỗi lần đổi tài khoản. Với Aki MCP Server, chỉ cần đổi Profile trình duyệt — nhiều tài khoản Claude Pro khác nhau, cùng trỏ về một máy local.

Điều khiển máy từ xa khi không ở bàn làm việc

Khi di chuyển hoặc dùng thiết bị khác: mở Claude Web, ChatGPT Mobile hoặc Grok để kiểm tra tiến độ build, đọc log server, dọn thư mục tạm, hay chạy an toàn git pull trên máy ở nhà.

Tự động hóa đám mây (Grok + Local MCP)

Kết hợp Scheduled Prompts của Grok với Aki MCP Server để biến máy tính thành một AI node headless. Đúng giờ hẹn, Grok gọi về kiểm tra hệ thống, quét log và cập nhật code mới nhất — không cần mở cửa sổ trình duyệt nào.

Bảo Mật Không Phải Ý Tưởng Thêm Vào Sau

Aki MCP Server so với Desktop Commander

Vì sao hard whitelist là yêu cầu bắt buộc khi một cổng MCP đối mặt trực tiếp với Internet.

Tiêu chí	Aki MCP Server	Desktop Commander
Môi trường kết nối	Claude Web, ChatGPT Web/Mobile, Grok qua Internet (HTTPS)	Chỉ Claude Desktop app cục bộ
Cơ chế bảo vệ Shell	Hard Whitelist: chỉ lệnh đã duyệt mới chạy; chặn ; & \| `	<strong>Blocklist</strong>: cho phép mọi thứ trừ danh sách cấm (dễ bị bypass bằng flag hoặc lệnh mới)
Chống Prompt Injection	Triệt để: kẻ tấn công không thể leo thang vì lệnh ngoài danh mục bị từ chối ngay lập tức	Rủi ro cao nếu AI bị lừa chạy lệnh chưa có trong blocklist
Xác thực & Cấp quyền	OAuth 2.1 + Passphrase consent + RFC 7591 DCR cho ChatGPT & Grok	Không có OAuth, chạy trực tiếp qua tiến trình cục bộ
Giao diện quản trị (Panel)	Web UI nội bộ (`127.0.0.1:9998`), token ngẫu nhiên bảo vệ, cấu hình allowlist trực quan	Chỉnh sửa file cấu hình JSON tĩnh bằng tay
Tìm kiếm file & thư mục	`local__find_path` quét 164k files trong 0.2s, tự bỏ qua node_modules/.git	Dùng lệnh tìm kiếm thông thường hoặc filesystem mặc định, dễ bị timeout

Kiến Trúc & Bảo Mật

Bảo mật đa tầng theo thiết kế

Dữ liệu của bạn được cô lập và bảo vệ ở từng chặng.

Lớp 1: Ingress & Cổng công khai

Gatekeeper & OAuth 2.1

Gatekeeper (Port 9999) là điểm tiếp nhận duy nhất từ Internet, đi qua Tailscale Funnel hoặc Cloudflare Tunnel.

Claude dùng Confidential Client ID/Secret.
ChatGPT & Grok tự đăng ký qua DCR (POST /register).
Mọi kết nối đều yêu cầu Passphrase trên trang Authorize.

gatekeeper.js :9999 (Cổng Công Khai)

Lớp 2: Điều phối & Bridge

Streamable Bridge & MCP Hub

Chuyển đổi Streamable HTTP từ AI web client sang SSE transport nội bộ của MCP Hub (Port 19999), chỉ bind loopback.

MCP Hub chỉ lắng nghe trên 127.0.0.1.
Multi-client multiplexing qua ID remapping.
API admin nội bộ không bao giờ lộ ra Internet.

mcp-hub :19999 (127.0.0.1 duy nhất)

Lớp 3: Quản trị & Lưu trữ

Userdata & panel cô lập

Token, passphrase, allowlist và cấu hình lưu ngoài thư mục source tại ~/.aki/mcpsv/ với quyền 0600.

Web Panel (:9998) bảo vệ bởi token dùng một lần.
Giới hạn đường dẫn qua roots.js.
Git clone luôn sạch — thông tin mật không bao giờ vào repo.

panel.js :9998 (Bảo Vệ Bằng Token)

Hệ Thống Công Cụ

Bộ công cụ local tích hợp (`local__*`)

Thiết kế tối ưu tốc độ, tiết kiệm ngữ cảnh và bảo mật chặt chẽ.

File System

`filesystem`

Cho phép AI đọc, tạo, sửa file an toàn trong các thư mục được cấp quyền ($MCP_DATA_DIR, ~/.aki, ~/.claude).

read_file, write_file, edit_file, list_directory

Siêu Tốc Độ

`local__find_path`

Quét toàn bộ cây thư mục chỉ trong 1 lần gọi (0.2s với 164k files), trả về cả file và thư mục, tự bỏ qua node_modules và .git.

find_path(query, max_results)

Tìm Nội Dung

`local__search_content`

Tìm nội dung trong file bằng regex mở rộng không phân biệt hoa thường (grep -iE), rất nhanh.

search_content(pattern, path)

Shell Whitelist

`local__run_cmd`

Thực thi lệnh shell nằm trong whitelist đã duyệt. Hỗ trợ tham số cwd để nhắm đúng thư mục dự án.

run_cmd(command, args, cwd)

AGY Plan Arm

`local__agy_run`

Chạy Antigravity CLI ở chế độ plan/chỉ đọc, ngữ cảnh rộng, phục vụ nghiên cứu sâu.

agy_run(prompt, model, effort)

Kiro Arm

`local__kiro_read`

Chạy Kiro CLI (khóa model Claude Sonnet) để đọc và đối chiếu cấu trúc dự án một cách độc lập.

kiro_read(prompt, cwd)

Bắt Đầu

Cài đặt & chạy

Chọn cách phù hợp với môi trường của bạn.

Cách 1: StandaloneKhuyến nghị — không cần Node.js

Không cần cài gì ngoài chính ứng dụng

Đóng gói sẵn Node runtime riêng và toàn bộ app cho mọi hệ điều hành. Tải launcher đúng nền tảng từ bản phát hành mới nhất trên GitHub — không phải nút xanh "Code" → "Download ZIP" phía trên, đó chỉ là mã nguồn không chạy được.

macOS: double-click aki-mcp-sv-<version>-macos.command (hoặc chạy từ Terminal)
Linux: chmod +x aki-mcp-sv-<version>-linux.run && ./aki-mcp-sv-<version>-linux.run
Windows: double-click aki-mcp-sv-<version>-windows.cmd (cần Git for Windows hoặc WSL trong PATH)

Tải từ GitHub Releases

Cách 2: Từ mã nguồnmacOS, Windows, Linux

Dành cho Developer đã có Node.js

Clone repo từ GitHub và chạy lệnh khởi động chuẩn.

# Clone repo

git clone https://github.com/lacvietanh/aki-mcp-sv.git

cd aki-mcp-sv

# Cài đặt & khởi chạy

npm install

npm start

npm start tự động cấu hình Funnel, sinh passphrase, khởi chạy Gatekeeper và mở Web Panel quản trị.

Cảnh báo bảo mật hệ điều hành lần chạy đầu

Bình thường với launcher chưa ký code, không phải dấu hiệu lỗi: cảnh báo tải file từ trình duyệt, macOS Gatekeeper, Windows SmartScreen, và (trên Linux) cần cấp quyền thực thi trước. Xem đầy đủ các bước xử lý trên GitHub

Tùy chọn Ingress linh hoạt (swappable edge)

1. Tailscale Funnel (mặc định)

Zero-config, tự bật cổng 9999 khi chạy npm start. Miễn phí trên mọi gói Tailscale.

2. Cloudflare Named Tunnel

Chạy với --tunnel <cred.json> --origin <url> để định tuyến qua Cloudflare của riêng bạn.

3. Custom Public Origin

Chạy với PUBLIC_ORIGIN=https://your-domain để trỏ tới reverse proxy HTTPS riêng của bạn.

Tích Hợp AI

Kết nối Claude, ChatGPT, Grok & Gemini

Hướng dẫn kết nối chi tiết cho từng AI web client.

Claude.ai Web Connector

Dành cho tài khoản Claude Pro / Team

1Vào claude.ai → Settings → Connectors → Add custom connector.
2Nhập Remote MCP server URL: https://your-machine.ts.net/mcp (được in ra khi server khởi chạy).
3Mở Advanced settings: dán OAuth Client ID và OAuth Client Secret từ terminal hoặc Panel.
4Nhấn Connect: trang xác nhận cục bộ mở ra — nhập Passphrase hiển thị trong control panel (hoặc ~/.aki/mcpsv/passphrase.txt) để phê duyệt.

ChatGPT Web & Mobile

Cần Developer mode (Plus/Pro/Business/Enterprise/Edu)

1Vào ChatGPT → Settings → Apps & Connectors (hoặc Security) → bật Developer mode.
2Tạo custom connector mới và dán MCP URL: https://your-machine.ts.net/mcp.
3Chọn OAuth → Advanced OAuth settings: đặt Registration URL là https://your-machine.ts.net/register (DCR).
4Giữ Registration method là DCR, auth method none. Nhập Passphrase trên màn hình xác nhận để hoàn tất.

Grok

Đã xác minh, sẵn sàng production

1Mở phần cài đặt connector của Grok và thêm một custom MCP connector mới.
2Dán cùng MCP URL — không cần Client ID, Grok tự đăng ký qua DCR (RFC 7591) giống hệt ChatGPT.
3Nhấn Connect và nhập Passphrase trên trang xác nhận cục bộ để phê duyệt.

Gemini

Thử nghiệm — chỉ gói trả phí

1Cần gói Gemini trả phí (Pro / Business / Enterprise) — gói miễn phí có thể không hỗ trợ custom app.
2Thêm custom app trỏ tới MCP URL, sau đó dán OAuth Client ID và Client Secret trong Advanced Settings — confidential client, giống hệt Claude.
3Nhập Passphrase trên trang xác nhận để phê duyệt.

Lưu ý: quá trình OAuth thành công và Gemini chấp nhận hướng dẫn, nhưng qua nhiều lần thử nghiệm, Gemini không phát hiện hoặc điều khiển được các MCP tools một cách ổn định — kết nối khỏe nhưng dùng tool không đáng tin cậy. Claude và Grok vẫn là hai client đáng tin cậy nhất hiện nay.

Trải Nghiệm Thực Tế

Hình Ảnh Minh Họa

Ảnh chụp thật, đã xác minh từ các tích hợp phía client.

Hộp thoại Custom Instructions của ChatGPT

Extension theo dõi usage của Claude Web

Extension theo dõi usage của Grok

Control panel — demo render trực quan Bản render tĩnh tại build-time từ đúng control panel thật, dùng dữ liệu ví dụ — không phải kết nối trực tiếp.