File .mcp.json

4 phút đọccập nhật 30/9/2026

.mcp.json ở gốc dự án khai báo các MCP server phạm vi project — commit vào git để cả nhóm có cùng công cụ. Nhắc lại các phạm vi ở bài Cài MCP đầu tiên.

Định dạng

json
{
  "mcpServers": {
    "so-viec-nha": {
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/mcp/server.js"],
      "env": {
        "DB_URL": "${DB_URL:-mongodb://localhost/so-viec-nha}"
      }
    },
    "tai-lieu": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TAI_LIEU_API_KEY}"
      }
    }
  }
}
LoạiTrường
Chạy trên máy (stdio)command, args, env
Từ xatype (http…), url, headers

Biến môi trường — không bao giờ ghi khoá thật

Cú phápNghĩa
${TEN_BIEN}Lấy từ biến môi trường
${TEN_BIEN:-mac-dinh}Lấy từ biến môi trường, không có thì dùng giá trị mặc định
${CLAUDE_PROJECT_DIR}Thư mục gốc dự án

Dùng được trong command, args, env, url, headers. Mỗi người tự đặt biến trên máy mình; file commit chỉ chứa tên biến. Xem Giữ bí mật.

Duyệt server của dự án

Khi mở dự án có .mcp.json lần đầu, Claude Code hỏi bạn có tin thư mục này và có dùng các server trong đó không. Đây là lớp bảo vệ: một repo lạ không tự bật được công cụ trên máy bạn. Đọc file trước khi đồng ý (Dùng công cụ bên thứ ba an toàn).

Lưu ý

Khi chạy không tương tác (claude -p), server trong .mcp.json được nạp mà không hỏi. Đừng chạy claude -p trong repo bạn chưa đọc .mcp.json.

Lệnh

terminal · gõ vào máy
claude mcp add --scope project --transport http <ten> <url>
claude mcp add --scope project <ten> -- <lenh> <tham-so...>
claude mcp list                  # trạng thái các server
claude mcp get <ten>             # chi tiết một server
claude mcp remove <ten> --scope project
claude mcp reset-project-choices # hỏi lại việc duyệt server của dự án

Trong phiên: /mcp để xem, bật/tắt, đăng nhập.

Lưu ý

Đối chiếu tài liệu chính thức ngày 30/09/2026; định dạng và lệnh có thể đổi.