MCP trong Claude Code: scope local, project, user và .mcp.json cho team

Bạn thêm một MCP server vào Claude Code, mở dự án khác thì không thấy đâu. Đồng nghiệp clone repo về thì lại bị hỏi "có tin server này không?". Hoặc tệ hơn: API key nằm chình ình trong file commit lên Git. Tất cả xuất phát từ việc chưa hiểu scope của MCP trong Claude Code: server được lưu ở đâu, ai thấy, và cấu hình nào thắng khi trùng tên.

Thêm server: hai kiểu chính

# Server từ xa qua HTTP (khuyến nghị)
claude mcp add --transport http github https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

# Server cục bộ qua stdio: mọi thứ sau -- là lệnh của server
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=xxx \
  -- npx -y airtable-mcp-server

Dấu -- rất quan trọng: nó ngăn Claude Code hiểu nhầm cờ của server là cờ của mình. Viết tắt: -t (transport), -H (header), -s (scope), -e (env). Transport SSE đã deprecate.

Ba scope

Khi trùng tên, thứ tự ưu tiên là: managed của tổ chức → local → project → user → server từ plugin → connector claude.ai. Bản ở nguồn cao nhất được dùng nguyên vẹn, không trộn từng trường.

.mcp.json cho team, không lộ bí mật

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

• ${VAR} và ${VAR:-mặc_định} dùng được trong command, args, env, url, headers. Mỗi người tự đặt biến trong môi trường của mình, file commit không chứa secret.
• Biến rỗng vẫn tính là "đã đặt", nên giá trị mặc định không được dùng.
• Để chống lộ thông tin, các biến credential như ANTHROPIC_API_KEY sẽ bị thay bằng chuỗi rỗng khi nằm trong url/headers của server từ xa.

Duyệt server dự án

Ở phiên tương tác, Claude Code hỏi trước khi dùng server trong .mcp.json; repo clone về không tự duyệt được server của chính nó. Đặt lại lựa chọn bằng claude mcp reset-project-choices. Lưu ý: ở claude -p và Agent SDK, server dự án được nạp không hỏi; muốn chặn, dùng --strict-mcp-config hoặc disabledMcpjsonServers.

Lệnh quản lý hay dùng

claude mcp list            # danh sách + tình trạng
claude mcp get github      # chi tiết một server
claude mcp remove github   # xoá (không thu hồi token!)
claude mcp logout github   # thu hồi token OAuth
/mcp                       # trong phiên: xem trạng thái, đăng nhập OAuth

Rủi ro và lưu ý

• Output lớn tốn context: Claude Code cảnh báo khi kết quả tool vượt 10.000 token, giới hạn mặc định 25.000 (đổi bằng MAX_MCP_OUTPUT_TOKENS).
• remove không thu hồi token: chạy logout trước nếu muốn vô hiệu hoá token đã cấp.
• Server dự án từ repo lạ: đọc .mcp.json trước khi duyệt, đặc biệt lệnh stdio vì nó chạy trên máy bạn.
• Trùng tên ở nhiều scope: bản local âm thầm thắng bản project, dễ gây "sao máy tôi khác máy bạn".

Áp dụng thế nào?

• Dev: Server cá nhân (ghi chú, lịch) để scope user; server thử nghiệm để local.
• Tech Lead: Commit .mcp.json với biến môi trường cho secret, ghi README hướng dẫn đặt biến.
• PM/Admin: Dùng managed MCP để chuẩn hoá server được phép cho cả tổ chức.