Bài 5.218 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

.mcp.json và phạm vi

Chia sẻ server MCP cho cả team bằng .mcp.json, giữ token trong biến môi trường, và nối GitHub để Claude đọc issue.

Ở 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:

JSON
{
  "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.json trước khi dùng. Trước khi duyệt, claude mcp list ghi ⏸ Pending approval. Lỡ từ chối thì chạy claude 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.json bị bỏ qua cho tới khi bạn tin thư mục đó.
  • Ngược lại, claude -p và Agent SDK không hỏi được, nên nạp server dự án luôn. Chạy claude -p trong repo lạ là để server của repo đó chạy. Muốn chặn một server, thêm nó vào disabledMcpjsonServers trong 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.

JSON
"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 list cảnh báo Missing environment variables: GITHUB_PAT, và server không kết nối được.
  • Không lộ giá trị: claude mcp get github hiệ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_KEY hay NPM_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.json lạ 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:

  1. 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.
  2. Đặt token vào biến môi trường trong shell, không đặt trong repo:
    Terminal
    export GITHUB_PAT=github_pat_...
  3. Thêm server vào .mcp.json của todo-api:
    JSON
    {
      "mcpServers": {
        "github": {
          "type": "http",
          "url": "https://api.githubcopilot.com/mcp/",
          "headers": {
            "Authorization": "Bearer ${GITHUB_PAT}"
          }
        }
      }
    }
  4. Mở claude trong thư mục đó, duyệt server khi được hỏi, rồi gõ /mcp. Dòng github phả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 each

Khi 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: /mcp trong phiên, hoặc claude mcp list ngoài terminal.
  • Tắt tạm mà không xóa cấu hình: chọn server trong /mcp và tắt. Lựa chọn được lưu cho riêng dự án đó trong ~/.claude.json, không đụng tới .mcp.json của team.
  • Xem chi tiết một server: claude mcp get github cho 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.json thì 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.

Luyện tập bài 5.2

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.