Ở bài 5.1 bạn nối một server bằng claude mcp add, và nó chỉ có trên máy bạn. Nhưng nếu cả team cần cùng server GitHub thì sao? Mỗi người tự gõ lệnh, tự đặt tên, và sớm muộn sẽ có người đặt khác. Bài này đưa cấu hình server vào repo bằng file .mcp.json, giữ token ngoài repo, rồi nối GitHub để Claude đọc issue của todo-api.
Ba nơi lưu server
Mỗi server được lưu ở một trong ba scope (phạm vi):
| Scope | Dùng được ở | Chia sẻ với team | Lưu ở |
|---|---|---|---|
| local (mặc định) | Chỉ dự án này | Không | ~/.claude.json |
| project | Chỉ dự án này | Có, qua git | .mcp.json ở gốc repo |
| user | Mọi dự án của bạn | Không | ~/.claude.json |
Chọn theo câu hỏi "ai cần server này, ở đâu":
- local: server bạn đang thử, hoặc server có thông tin đăng nhập bạn không muốn đưa vào git.
- project: server cả team cần cho repo này. Đây là scope của bài.
- user: công cụ cá nhân bạn dùng ở mọi dự án, như server docs ở bài 5.1.
Đừng nhầm "local" của MCP với file .claude/settings.local.json: server local nằm trong ~/.claude.json ở thư mục nhà, không nằm trong repo.
Nếu cùng một tên server có ở nhiều nơi, Claude Code chỉ dùng một định nghĩa, theo thứ tự ưu tiên: local, rồi project, rồi user, rồi plugin, cuối cùng là connector của claude.ai. Các trường không được gộp: bản local thắng thì cả bản project bị bỏ qua. Muốn đổi scope của một server, gỡ nó rồi thêm lại ở scope mới.
File .mcp.json
.mcp.json nằm ở gốc repo và có dạng:
{
"mcpServers": {
"claude-code-docs": {
"type": "http",
"url": "https://code.claude.com/docs/mcp"
},
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
}
}
}Server HTTP cần type và url; server stdio cần command và args. Bạn có thể viết tay, hoặc chạy claude mcp add … --scope project để Claude Code tự tạo, tự cập nhật file. Claude Code đọc .mcp.json khi mở phiên, nên sửa xong thì mở phiên mới.
Vì file này đi theo repo, ai clone về cũng nhận được nó, kể cả repo của người lạ. Claude Code xử lý chuyện đó như sau:
- Trong phiên tương tác, Claude Code hỏi bạn duyệt từng server trong
.mcp.jsontrước khi dùng. Trước khi duyệt,claude mcp listghi⏸ Pending approval. Lỡ từ chối thì chạyclaude mcp reset-project-choicesđể được hỏi lại. - Một repo không tự duyệt được server của chính nó: các cài đặt duyệt sẵn commit trong
.claude/settings.jsonbị bỏ qua cho tới khi bạn tin thư mục đó. - Ngược lại,
claude -pvà Agent SDK không hỏi được, nên nạp server dự án luôn. Chạyclaude -ptrong repo lạ là để server của repo đó chạy. Muốn chặn một server, thêm nó vàodisabledMcpjsonServerstrong cài đặt.
Token không bao giờ vào repo
Server GitHub cần token. Token đó không bao giờ được nằm trong .mcp.json, vì file sẽ được commit. Cách làm đúng là biến môi trường: trong file chỉ ghi tên biến, giá trị nằm trong shell của từng người.
"headers": {
"Authorization": "Bearer ${GITHUB_PAT}"
}Claude Code thay ${GITHUB_PAT} bằng giá trị biến khi kết nối. Biến dùng được trong command, args, env, url và headers. Có thêm dạng ${VAR:-mặc_định} cho giá trị mặc định khi biến chưa đặt.
Ba điều chúng tôi kiểm chứng khi thử:
- Quên đặt biến: cấu hình vẫn nạp, nhưng
claude mcp listcảnh báoMissing environment variables: GITHUB_PAT, và server không kết nối được. - Không lộ giá trị:
claude mcp get githubhiện header làBearer ${GITHUB_PAT}, theo tên chứ không phải token thật. Chụp màn hình chia sẻ cũng an toàn. - Một số tên bị cấm: biến chứa thông tin đăng nhập của chính Claude Code hay nhà cung cấp, như
ANTHROPIC_API_KEYhayNPM_TOKEN, luôn được đọc là rỗng khi gửi tới server từ xa. Đây là cách Claude Code ngăn một.mcp.jsonlạ lấy cắp chìa khóa của bạn. Hãy đặt tên riêng nhưGITHUB_PAT.
Nối GitHub
GitHub có MCP server chính thức chạy từ xa tại https://api.githubcopilot.com/mcp/, xác thực bằng personal access token. Các bước:
- Mở
github.com/settings/personal-access-tokens, tạo một fine-grained token chỉ cho những repo bạn cần. Muốn Claude chỉ đọc thì chỉ cấp quyền đọc. - Đặt token vào biến môi trường trong shell, không đặt trong repo:Terminal
export GITHUB_PAT=github_pat_... - Thêm server vào
.mcp.jsoncủatodo-api:JSON{ "mcpServers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_PAT}" } } } } - Mở
claudetrong thư mục đó, duyệt server khi được hỏi, rồi gõ/mcp. Dònggithubphải có dấu ✔. Nếu thấy ✘ kèm lỗi 401, token sai, hết hạn hoặc không có quyền với repo.
Docs cũng đưa cách nhanh cho dùng một mình: claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer …". Cách này lưu token vào ~/.claude.json ở scope local, ngoài repo. Lưu ý claude mcp add không kiểm tra token: token sai vẫn được lưu, và chỉ tới khi kết nối mới báo lỗi.
Làm việc với GitHub
Nối xong, bạn hỏi Claude bằng lời bình thường:
Summarise the open issues in app-works-247/todo-api, one line eachKhi thử, Claude dùng tool search để tìm công cụ liên quan tới issue, gọi mcp__github__list_issues, rồi trả lời. Nó trả về đúng ba issue đang mở của todo-api, mỗi issue một dòng kèm nhãn: hai bug (xóa hai lần trả 500, JSON hỏng trả 500) và một đề xuất thêm bộ lọc ?done=. Đây chính là những việc bạn sẽ giao cho Claude ở các bài sau. Vài câu khác docs gợi ý:
- "Review PR #456 and suggest improvements"
- "Create a new issue for the bug we just found"
- "Show me all open PRs assigned to me"
Hai câu sau cần token có quyền ghi. Với token chỉ đọc, Claude đọc được nhưng tạo issue sẽ thất bại. Đó là điều tốt khi bạn mới bắt đầu: bài 5.3 bàn kỹ chuyện cấp bao nhiêu quyền là đủ.
Kết hợp với bài trước: issue mô tả bug, skill pr-review giữ checklist, subagent debugger sửa trên worktree riêng. Giờ Claude đọc được đầu vào của cả quy trình mà không cần bạn chép tay.
Quản lý server hằng ngày
- Xem trạng thái:
/mcptrong phiên, hoặcclaude mcp listngoài terminal. - Tắt tạm mà không xóa cấu hình: chọn server trong
/mcpvà tắt. Lựa chọn được lưu cho riêng dự án đó trong~/.claude.json, không đụng tới.mcp.jsoncủa team. - Xem chi tiết một server:
claude mcp get githubcho biết scope, trạng thái, URL và header (theo tên biến). - Gỡ:
claude mcp remove github. Server nằm trong.mcp.jsonthì xóa khỏi file rồi commit.
Quy tắc ngắn cho cả team: .mcp.json mô tả server nào, biến môi trường giữ bí mật, /mcp để kiểm tra. Ai mới vào team chỉ cần clone repo, đặt biến của mình, duyệt server một lần là có cùng bộ công cụ như mọi người.