MCP APICập nhật 2026-04-29

focus.camp expose tối đa 22 tools qua MCP (Model Context Protocol) để agent ngoài (vd goclaw.sh, Claude Desktop, custom agents) đọc data + thực thi action trên cộng đồng của bạn.

Quickstart

  1. Vào Settings của community → section API Keys (MCP)
  2. Click + Tạo API key mới, đặt tên (vd "Goclaw production") và chọn scope tối thiểu cần dùng
  3. Copy plaintext key (chỉ hiện 1 lần — lưu chỗ an toàn)
  4. Trong goclaw / MCP client, thêm server với:
    • URL: https://focus.camp/api/mcp
    • Transport: Streamable HTTP
    • Header: Authorization: Bearer fc_live_…
  5. Test bằng npx @modelcontextprotocol/inspector hoặc tool list trong goclaw

Authentication

Mỗi key gắn với 1 community. Agent CANNOT truy cập community khác qua key đó — community ID được resolve server-side. Action ghi (createPost, createChallenge…) được thực hiện AS owner của community.

Authorization: Bearer fc_live_<32 ký tự>

Scopes

  • read — xem dữ liệu community, posts, challenges, members, XP
  • write — tạo/sửa content, duyệt submission, gửi notification
  • admin — xoá post, quản lý member, course, community info

Giới hạn key theo challenge

Khi tạo key có thể chọn 🎯 Giới hạn theo challenge — key đó chỉ làm việc được với các challenge đã chọn (enforce server-side, không phải dặn dò trong prompt). Để trống = không giới hạn. Với key bị giới hạn:

  • challenges_list chỉ trả về các challenge được phép
  • challenges_get / challenges_list_pending_checkins / challenges_update ngoài danh sách → lỗi challenge_not_allowed_for_this_key
  • checkins_review chỉ duyệt được check-in thuộc challenge được phép
  • challenges_create bị chặn hoàn toàn (key gắn với challenge có sẵn)
  • Webhook provision member (challengeSlug) cũng chỉ nhận challenge trong danh sách
  • Các tool ngoài challenge (posts, members, courses…) vẫn theo scope bình thường

Dùng khi thuê người ngoài / agent bên thứ ba vận hành đúng 1 challenge — họ không đụng được challenge khác kể cả khi agent "quên" lời dặn.

Rate limits

  • 60 calls/phút per API key
  • Ngoài quota → HTTP 429
  • Plan hết hạn → write tools throw error (read tools vẫn chạy)

Tools

Read (10)

  • community_get_info — name, plan, member count
  • community_get_stats — counts last N days (posts, checkins, new members)
  • community_list_members — paginated members + role/tier/level
  • community_get_member — full profile by userId
  • posts_list — feed (POST/QUESTION/SIGNAL), filter by pillar, sort latest/popular
  • posts_get — single post + comments
  • challenges_list — by status (OPEN/ACTIVE/COMPLETED)
  • challenges_get — challenge + tasks + member count
  • challenges_list_pending_checkins — for review
  • xp_list_recent — recent XP ledger (community or per-user)

Write (6)

  • posts_create — new POST/QUESTION/SIGNAL
  • posts_update — edit body/title/pillar
  • challenges_create — challenge + N tasks (software factory pattern: spec → instance)
  • challenges_update — settings + freeze + banner
  • checkins_review — APPROVE / REJECT
  • notifications_send — inbox notification to specific member

Admin (6)

  • posts_delete
  • members_update_role — MEMBER / MOD / ADMIN
  • members_remove
  • courses_create
  • courses_add_lesson
  • community_update_info — name/tagline/description

Goclaw setup

Trong goclaw web UI:

  1. Tools → Custom MCP Server → Add
  2. Type: Streamable HTTP
  3. Endpoint: https://focus.camp/api/mcp
  4. Auth header: Authorization: Bearer fc_live_…
  5. Save → agent của bạn sẽ thấy các tools tương ứng với scope của key

System prompt mẫu cho agent

Bạn là community manager của focus.camp.
Bạn có quyền truy cập các tools của community qua MCP, tuỳ theo scope của API key.

Khi user yêu cầu hành động trên community:
- Đọc state hiện tại trước (community_get_info, community_get_stats)
- Confirm với user trước khi gọi write tools
- Sau khi action xong, summarize kết quả ngắn gọn

Khi tạo challenge:
- Hỏi mục tiêu + audience trước
- Generate description + N tasks (1 task / ngày)
- Gọi challenges_create với tasks array
- Trả lại slug để user xem

Activity log

Mọi tool call được log trong Settings → Hoạt động Agent. Bạn xem được tool nào agent gọi, thành công/lỗi, thời gian thực thi.

Security

  • Plaintext key chỉ hiện 1 lần — sau đó chỉ lưu sha256 hash
  • Tạo key theo quyền tối thiểu: dùng read trước, chỉ bật write/admin khi agent thật sự cần
  • Revoke ngay lập tức tại Settings nếu nghi key leak
  • Set expiresIn để key tự hết hạn
  • Tool calls được log 30 ngày — owner audit được

Hỗ trợ

Câu hỏi / bug / request thêm tool: support@focus.camp