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

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

Giải pháp khắc phục toàn bộ hạn chế của API đắt đỏ và các ứng dụng Desktop bị khóa thiết bị.

Tận dụng Quota Web/Pro siêu rẻ

Gói Claude Pro / ChatGPT Plus hàng tháng có chi phí rẻ hơn hàng chục lần so với trả per-token qua API khi làm việc với các dự án lớn cần đọc toàn bộ mã nguồn và quét log liên tục. Aki MCP giúp bạn mang sức mạnh của tài khoản Web vào trực tiếp mã nguồn local.

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à mỗi lần đổi tài khoản phải đăng xuất phiền toái. Với Aki MCP, bạn chỉ cần chuyển đổi các Profile trình duyệt (nhiều tài khoản Claude Pro khác nhau) và tất cả đều kết nối mượt mà về cùng một máy tính local.

Điều khiển máy từ xa khi ở ngoài (Away from desk)

Khi bạn đang di chuyển trên đường hoặc dùng điện thoại/laptop khác: mở Claude Web, ChatGPT Mobile hoặc Grok để kiểm tra tiến độ build, xem log lỗi server, dọn dẹp thư mục tạm, hay chạy git pull trên máy tính ở nhà một cách an toàn.

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

Kết hợp tính năng Scheduled Prompts của Grok với Aki MCP để biến máy tính thành "trạm AI tự vận hành" (Headless AI Node). Đúng giờ đã hẹn, Grok tự động gọi về máy local để kiểm tra hệ thống, quét log, cập nhật repo mà bạn không cần mở bất kỳ cửa sổ trình duyệt nào.

Bảo Mật Vượt Trội

Khác biệt giữa Aki MCP và Desktop Commander

Vì sao Whitelist nghiêm ngặt là yêu cầu sống còn khi mở cổng MCP ra Internet.

Tiêu chí so sánh	Aki MCP Server	Desktop Commander
Môi trường kết nối	Claude Web, ChatGPT Web/Mobile, Grok qua Internet (HTTPS)	Chỉ dành cho Claude Desktop App cục bộ
Cơ chế bảo vệ Shell	Hard Whitelist: Chỉ chạy các lệnh trong danh sách đã duyệt; chặn ; & \| `	Blocklist: Cho phép mọi thứ ngoại 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ị đánh lừa thực thi các 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	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-gated ngẫu nhiên, 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ế (Security by Construction)

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

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 ra ngoài internet thông 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 nhập Passphrase xác nhận trên trang Authorize.

gatekeeper.js :9999 (Public Edge)

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

Streamable Bridge & MCP Hub

Chuyển đổi giao thức Streamable HTTP từ các AI Web client sang SSE transport nội bộ của MCP Hub (Port 19999), chỉ bind trên 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ờ bị lộ ra ngoài internet.

mcp-hub :19999 (127.0.0.1 Only)

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

Isolated Userdata & Panel

Toàn bộ token, passphrase, allowlist và cấu hình lưu trữ ngoài thư mục source code tại ~/.aki/mcpsv/ với quyền truy cập 0600.

Web Panel (:9998) bảo vệ bởi One-time Token.
Kiểm tra biên giới hạn đường dẫn file qua roots.js.
Git clone luôn sạch, không bao giờ lộ thông tin mật.

panel.js :9998 (Token Protected)

Hệ Thống Công Cụ

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

Được thiết kế tối ưu hóa tốc độ, tiết kiệm ngữ cảnh và bảo mật tuyệt đối.

File System

`filesystem`

Cho phép AI đọc, tạo, chỉnh 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à folder, tự bỏ qua node_modules và .git.

find_path(query, max_results)

Tìm Nội Dung

`local__search_content`

Tìm kiếm nội dung bên trong file bằng biểu thức chính quy mở rộng không phân biệt hoa thường (grep -iE) nhanh chóng.

search_content(pattern, path)

Allowlist Shell

`local__run_cmd`

Thực thi các lệnh shell nằm trong danh sách trắng (Whitelist) đã được phê duyệt. Hỗ trợ truyền tham số cwd đến thư mục dự án cần thực thi.

run_cmd(command, args, cwd)

AGY Plan Arm

`local__agy_run`

Cánh tay AI hỗ trợ chạy Antigravity CLI ở chế độ lập kế hoạch / chỉ đọc (plan mode / read-only) với ngữ cảnh rộng.

agy_run(prompt, model, effort)

Kiro Arm

`local__kiro_read`

Cánh tay AI chạy Kiro CLI (khóa model Claude Sonnet) để đọc hiểu cấu trúc dự án và đối chiếu logic chuyên sâu.

kiro_read(prompt, cwd)

Bắt Đầu Sử Dụng

Hướng dẫn Cài đặt & Chạy nhanh

Chọn phương thức phù hợp nhất với môi trường làm việc của bạn.

Cách 1: Standalone PackagemacOS Apple Silicon

Không cần cài đặt Node.js hay npm

Gói phần mềm đã đóng gói sẵn toàn bộ môi trường Node runtime, dependencies và code ứng dụng. Tải về và khởi chạy trong 5 giây.

Tải bản phát hành mới nhất từ GitHub Releases.
Giải nén thư mục và mở Terminal tại thư mục đó.
Chạy lệnh: ./start.sh

Tải bản Standalone Release

Cách 2: Standard CLImacOS, Windows, Linux

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

Cài đặt trực tiếp từ kho mã nguồn 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 sẽ tự động cấu hình Funnel, sinh passphrase, khởi chạy Gatekeeper và mở Web Panel quản trị.

Tùy chọn Ingress Linh Hoạt (Swappable Edge)

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

Zero-config, tự động 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 cờ --tunnel <cred.json> --origin <url> để định tuyến qua Cloudflare của bạn.

3. Custom Public Origin

Chạy với biến môi trường PUBLIC_ORIGIN=https://your-domain để trỏ đến HTTPS reverse proxy riêng.

Tích Hợp AI

Kết nối Claude Web & ChatGPT

Các bước kết nối chi tiết từng nền tảng AI Web với Aki MCP Server.

Claude.ai Web Connector

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

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

ChatGPT Web & Mobile

Dành cho ChatGPT Plus / Pro với Developer Mode

1Vào ChatGPT → Settings → Security (hoặc Apps) → 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: điền Registration URL là https://your-machine.ts.net/register (DCR).
4Đặt Registration method: DCR, Auth method: none. Nhập Passphrase trên màn hình phê duyệt để hoàn tất.

Giao Diện Thực Tế

Hình ảnh Trực quan Bảng điều khiển

Trực tiếp từ trải nghiệm thực tế trên hệ thống Aki MCP Server.

Bảng điều khiển Web Panel (:9998)

Cấu hình ChatGPT Connector (DCR)

Kết nối thực tế trên Claude Web