MCP local-first là gì? Khi nào mới cần ingress?
MCP local-first ưu tiên kết nối loopback trên chính máy, chỉ bật ingress khi client web cần truy cập từ xa. Cách chọn Local hay Web và giảm bề mặt mạng.
MCP local-first là cách vận hành MCP server ưu tiên client và server giao tiếp ngay trên cùng máy qua địa chỉ loopback, thay vì mặc định đưa endpoint ra internet. Với AkiMCP 2.1, Gatekeeper luôn bind 127.0.0.1 và ingress chỉ được bật khi một client Web thật sự cần truy cập từ xa.
Local và Web khác nhau ở đâu?
- ◆Local: Postman, Cursor, Claude Code, AGY, Codex hoặc client khác chạy cùng máy gọi endpoint loopback; không cần ingress.
- ◆Web: Claude, Grok, ChatGPT, Gemini chạy trên web hoặc hạ tầng bên ngoài cần một địa chỉ truy cập được từ internet; lúc này mới cấu hình ingress.
- ◆Xác thực: cả hai đường vẫn cần token hợp lệ; loopback không thay thế kiểm soát truy cập.
Ví dụ: nối Codex vào engine local
Thêm đoạn sau vào cuối ~/.codex/config.toml (không ghi đè file), thay YOUR_LOCAL_ACCESS_TOKEN bằng token lấy từ panel. Codex gọi engine qua streamable HTTP, token nằm ngay trong cấu hình nên không cần export biến môi trường:
[mcp_servers.aki-mcp]
url = "http://127.0.0.1:9999/mcp"
http_headers = { "Authorization" = "Bearer YOUR_LOCAL_ACCESS_TOKEN" }Dùng 127.0.0.1 thay vì localhost: trên macOS, localhost có thể phân giải sang IPv6 ::1 trong khi server chỉ lắng nghe IPv4. Token vẫn bắt buộc vì một trang web độc hại trong trình duyệt cùng máy có thể gọi 127.0.0.1 ở nền; nếu bỏ token, việc đó thành chạy lệnh từ xa hoặc lấy cắp file cục bộ.
Vì sao không nên bắt buộc ingress?
Bắt buộc ingress khiến một tác vụ hoàn toàn cục bộ phụ thuộc thêm vào mạng và một lớp chuyển tiếp không cần thiết. Local-first tách hai nhu cầu: công việc trên máy vẫn chạy khi ingress không có, còn truy cập Web được bật có chủ đích.
Lợi ích thực tế là cấu hình ban đầu ngắn hơn và lỗi dễ khoanh vùng hơn. Nếu Local hoạt động nhưng Web không hoạt động, vấn đề nằm ở ingress thay vì lõi MCP.
Khi nào nên bật ingress?
Chỉ bật ingress khi client không chạy trên cùng máy, chẳng hạn một giao diện AI trên web cần gọi tool ở máy cá nhân. Khi chưa có ingress, các endpoint OAuth của luồng Web trong AkiMCP 2.1 trả 503 để chỉ đúng lớp đang thiếu, còn /mcp local vẫn phục vụ bình thường. Ingress gắn thêm (qua panel hoặc cờ --tunnel, biến PUBLIC_ORIGIN) có hiệu lực sau khi khởi động lại.
Panel AkiMCP 2.1 gom connector theo nhóm Local/Web để quyết định này xuất hiện ngay tại nơi sao chép cấu hình. Xem bản tin AkiMCP 2.1 để biết toàn bộ thay đổi.