Tài liệu API & MCP
Gọi thẳng REST API của MMO ALL bằng API key, hoặc nối một AI coding client (Claude Code, Cursor, ...) qua máy chủ MCP để cập nhật build log và roadmap dự án.
1. Lấy API key
Mỗi API key gắn với chính tài khoản của bạn nhưng hẹp hơn: chỉ mang đúng phạm vi quyền (scope) bạn chọn lúc tạo, và luôn có hạn sử dụng. Tạo và quản lý key tại màn "Quản lý API key" trong Cài đặt.
2. Xác thực
Gắn API key vào header Authorization của mọi request:
Authorization: Bearer mmo_pat_...API key không mang role nào của tài khoản — không gọi được endpoint cần quyền quản trị. Quyền của nó chỉ đến từ scope đã chọn lúc tạo key; thiếu scope cần thiết trả về lỗi 403.
Phạm vi quyền (scope) và route tương ứng
| Scope | Route |
|---|---|
| Đọc bài viết & bình luận | GET /api/v1/posts/**, GET /api/v1/comments/**, GET /api/v1/search, GET /api/v1/platform/**, GET /api/v1/media/** |
| Ghi bài viết & bình luận | POST/PATCH/DELETE /api/v1/posts/**, POST/PATCH/DELETE /api/v1/comments/**, POST /api/v1/media |
| Đọc việc làm | GET /api/v1/jobs/** |
| Ghi việc làm | POST/PATCH/DELETE /api/v1/jobs/** |
| Đọc hồ sơ | GET /api/v1/users/** |
| Đọc dự án | GET /api/v1/projects/** |
| Ghi dự án | POST/PATCH/DELETE /api/v1/projects/** |
| Đọc Insight GitHub | GET /api/v1/github/** |
| Đọc Opportunity Radar | GET /api/v1/radar/** |
3. Máy chủ MCP — build log & roadmap
Máy chủ MCP (Model Context Protocol) tối giản, để AI coding client cập nhật trực tiếp build log và roadmap của dự án thay vì copy-paste sang web. Transport Streamable HTTP, không trạng thái (stateless), JSON thuần — hỗ trợ ba phiên bản protocol 2025-11-25, 2025-06-18 và 2025-03-26.
Endpoint: POST /api/v1/mcp
Bảy tool
| Tool | Scope | Ghi chú |
|---|---|---|
list_my_projects | Đọc dự án | Dự án người gọi đứng tên — điểm khởi đầu của mọi luồng làm việc. |
get_roadmap | Đọc dự án | Danh sách milestone, sắp theo thứ tự hiển thị. |
create_milestone | Ghi dự án | Chỉ chủ dự án (OWNER) mới gọi được. |
update_milestone | Ghi dự án | Chỉ OWNER; field không gửi lên thì giữ nguyên giá trị cũ. |
delete_milestone | Ghi dự án | Chỉ OWNER; xoá thật, không hoàn tác được. |
list_build_logs | Đọc dự án | Đọc lại build log đã đăng của một dự án. |
create_build_log | Ghi bài viết & bình luận | Chủ dự án hoặc thành viên đều gọi được, không chỉ OWNER. |
Đủ MỘT trong ba scope projects.read, projects.write hoặc content.write là API key qua được cổng vào endpoint — nhưng mỗi tool bên trong vẫn tự đòi đúng scope riêng (bảng trên); thiếu thì cuộc gọi trả về isError, không phải HTTP 403.
Kết nối một client
Ví dụ với Claude Code:
claude mcp add --transport http mmoall https://api.mmoall.com/api/v1/mcp \
--header "Authorization: Bearer mmo_pat_..."