Cấu hình MCP trong Claude Code CLI

Claude Code là CLI (command-line interface) chính thức của Anthropic, chạy trực tiếp trong terminal và hỗ trợ MCP (Model Context Protocol — giao thức mở giúp AI agent gọi tool, đọc resource, và dùng prompt có sẵn từ các server bên ngoài) như một cơ chế native. Điểm khác biệt so với việc tự viết function calling thủ công: bạn không cần định nghĩa schema tool bằng tay, không cần viết code xử lý response — chỉ cần khai báo MCP server một lần, Claude Code tự động discover toàn bộ tool mà server đó cung cấp và gọi chúng khi cần trong lúc bạn chat. Bài này đi sâu vào đúng một việc: cấu hình MCP trong Claude Code CLI, từ cài đặt môi trường, dùng lệnh claude mcp add, chỉnh tay file settings.json, cho tới cách xác thực kết nối và xử lý lỗi thường gặp. Đây là kiến thức nền cần nắm chắc trước khi khai thác bất kỳ MCP server cụ thể nào (filesystem, GitHub, database, browser automation...) ở các bài sau trong module.

Chuẩn bị trước khi cấu hình: cài Claude Code CLI và setup môi trường

Trước khi đăng ký MCP server nào, môi trường chạy Claude Code phải ổn định. Yêu cầu tối thiểu: Node.js bản 18 trở lên (khuyến nghị dùng bản LTS mới nhất, vì nhiều MCP server community chạy qua npx và một số package đòi hỏi Node 20+). Kiểm tra nhanh:

node --version
npm --version

Cài Claude Code CLI qua npm:

npm install -g @anthropic-ai/claude-code

Xác nhận cài đặt thành công:

claude --version
claude doctor

claude doctor là lệnh chẩn đoán hữu ích ít người biết — nó kiểm tra phiên bản Node, quyền thực thi, đường dẫn cấu hình, và cảnh báo nếu có xung đột với các bản Claude Code cũ còn sót lại trên máy (ví dụ cài qua cả npm và Homebrew cùng lúc, gây lỗi PATH khó hiểu).

Đăng nhập và cấp quyền

Chạy claude lần đầu trong terminal sẽ mở luồng đăng nhập (đăng nhập bằng tài khoản Claude.ai/Console, hoặc dùng API key nếu bạn cấu hình qua biến môi trường ANTHROPIC_API_KEY). MCP chỉ hoạt động sau khi phiên đăng nhập đã ổn định — nếu bạn thêm MCP server trước khi đăng nhập, cấu hình vẫn được lưu, nhưng Claude Code sẽ không thể khởi động kết nối tới server đó cho tới khi bạn xác thực xong.

Thư mục project và quyền tin cậy (trust)

Claude Code phân biệt rõ project theo đường dẫn thư mục hiện tại (cwd). Lần đầu mở Claude Code trong một thư mục mới, bạn sẽ được hỏi có "trust" (tin cậy) thư mục này không — đây là cơ chế bảo vệ quan trọng vì MCP server có thể có quyền đọc/ghi file hoặc gọi API bên ngoài. Nếu bạn dự định khai báo MCP server ở scope project (chia sẻ với cả team qua file .mcp.json, sẽ nói ở phần sau), hãy đảm bảo thư mục đó đúng là repo bạn kiểm soát, tránh trust nhầm một thư mục lạ rồi vô tình chạy MCP server không rõ nguồn gốc.

Mẹo: Chạy claude doctor ngay sau khi cài đặt và mỗi khi gặp lỗi kết nối MCP khó hiểu — phần lớn lỗi "server failed to connect" ban đầu thực ra là do Node.js version không tương thích hoặc PATH bị xung đột, không phải do cấu hình MCP sai.

Thêm MCP server bằng lệnh claude mcp add

Cách nhanh và được khuyến nghị nhất để đăng ký MCP server là dùng lệnh có sẵn của CLI, không cần tự tay sửa JSON. Cú pháp cơ bản:

claude mcp add <tên-server> -- <lệnh-khởi-chạy-server>

Phần trước dấu -- là tên định danh (identifier) bạn tự đặt cho server, phần sau -- là câu lệnh thực sự dùng để chạy MCP server đó (thường là một tiến trình stdio — giao tiếp qua standard input/output). Ví dụ đăng ký server filesystem, cho phép agent đọc/ghi file trong một thư mục cụ thể:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects/my-app

Truyền biến môi trường (environment variable) cho server

Nhiều MCP server cần secret (token, API key) để gọi ra dịch vụ ngoài. Dùng flag -e:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx -- npx -y @modelcontextprotocol/server-github

Scope: local, project, hay user?

Claude Code hỗ trợ ba scope khác nhau cho MCP server, quyết định server đó được lưu ở đâu và ai dùng được:

claude mcp add my-tool -- npx -y some-mcp-server

claude mcp add shared-tool --scope project -- npx -y some-mcp-server

claude mcp add personal-tool --scope user -- npx -y some-mcp-server

Chọn scope sai là nguyên nhân phổ biến gây nhầm lẫn trong team: dùng local (mặc định) cho một tool bạn nghĩ cả team cần dùng thì chỉ mình bạn thấy nó hoạt động; ngược lại đăng ký project cho một token cá nhân (API key riêng của bạn) thì token đó lỡ tay bị commit vào .mcp.json và push lên remote — rất nguy hiểm. Quy tắc thực dụng: server không chứa secret cá nhân và cần đồng bộ cho cả team → project; server có secret riêng hoặc chỉ bạn dùng → local hoặc user.

Server dùng transport HTTP/SSE (remote server)

Không phải mọi MCP server chạy local qua stdio — nhiều dịch vụ SaaS cung cấp MCP server dạng remote, kết nối qua HTTP hoặc SSE (Server-Sent Events):

claude mcp add --transport sse linear https://mcp.linear.app/sse

claude mcp add --transport http notion https://mcp.notion.com/mcp

Cấu hình phức tạp bằng JSON trực tiếp

Khi cần khai báo nhiều biến môi trường, header xác thực, hoặc cấu hình lồng nhau phức tạp, dùng claude mcp add-json thay vì gõ từng flag:

claude mcp add-json custom-server '{
  "command": "node",
  "args": ["./mcp-servers/custom/index.js"],
  "env": {
    "API_KEY": "sk-xxxxx",
    "LOG_LEVEL": "debug"
  }
}'

Mẹo: Khi thêm server bằng npx -y <package>@latest (hoặc không ghim version), hãy chủ động pin về một version cụ thể cho môi trường CI/production, ví dụ npx -y @modelcontextprotocol/server-github@2024.11.5 — tránh trường hợp package community tự ý cập nhật, đổi behavior hoặc bị compromise (supply-chain risk) mà bạn không hề biết.

Cấu hình MCP server thủ công qua .claude/settings.json

Đây là phần dễ gây nhầm lẫn nhất với người mới, nên cần làm rõ ngay: định nghĩa server thật (lệnh chạy, biến môi trường, transport) nằm ở file .mcp.json (project, được tạo tự động khi bạn dùng --scope project ở phần trên) hoặc ở entry mcpServers trong ~/.claude.json (cho scope local/user). File .claude/settings.json không lưu định nghĩa server — nó quản lý quyền và hành vi liên quan tới MCP: server nào được tự động cho phép chạy, tool nào cần hỏi xác nhận, có bật tất cả MCP server của project hay không.

Ví dụ .mcp.json — nơi định nghĩa server thật (scope project)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Ví dụ .claude/settings.json — nơi quản lý quyền cho MCP

{
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["filesystem"],
  "disabledMcpjsonServers": ["postgres"],
  "permissions": {
    "allow": [
      "mcp__filesystem__read_file",
      "mcp__filesystem__list_directory"
    ],
    "ask": [
      "mcp__postgres__query"
    ]
  }
}

Giải thích các key quan trọng:

• enableAllProjectMcpServers: nếu true, tự động chấp nhận toàn bộ server khai báo trong .mcp.json mà không hỏi lại — nên để false cho repo dùng chung, tránh member mới clone về bị chạy MCP server lạ mà không hay biết.
• enabledMcpjsonServers / disabledMcpjsonServers: whitelist/blacklist tên server cụ thể từ .mcp.json — cho phép bật chọn lọc thay vì tất cả-hoặc-không-gì.
• permissions.allow / permissions.ask: kiểm soát ở cấp độ tool cụ thể, theo định dạng mcp__<tên-server>__<tên-tool>. Đặt vào allow nghĩa là tool đó chạy không cần hỏi lại mỗi lần; đặt vào ask (hoặc không khai báo — hành vi mặc định) nghĩa là Claude Code sẽ luôn hỏi xác nhận trước khi gọi.

Thứ tự ưu tiên (precedence) giữa các file settings

Claude Code đọc cấu hình theo nhiều tầng, tầng sau có thể override tầng trước: enterprise managed settings (do tổ chức áp đặt, cao nhất) → CLI flags khi khởi chạy → .claude/settings.local.json (cấu hình cá nhân, không commit, để trong .gitignore) → .claude/settings.json (chia sẻ với team, có commit) → user settings (~/.claude/settings.json, global cho mọi project). Nếu bạn muốn override tạm thời một permission chỉ cho riêng máy mình mà không ảnh hưởng team, sửa ở settings.local.json — không sửa trực tiếp settings.json đã commit.

Mẹo: Luôn để .claude/settings.local.json vào .gitignore ngay từ đầu project, và dùng nó để override permission cá nhân (ví dụ tạm cho phép một tool "nguy hiểm" trong lúc bạn đang debug) — giữ settings.json chính (đã commit) chỉ chứa cấu hình an toàn, đồng thuận cho cả team.

Kiểm tra và xác thực kết nối MCP trong Claude Code CLI

Sau khi đăng ký, luôn xác thực kết nối trước khi giao việc thật cho agent — đừng giả định server "chắc là chạy được".

Kiểm tra ngoài session (không cần mở chat)

claude mcp list

Kết quả mong đợi:

filesystem: npx -y @modelcontextprotocol/server-filesystem ./src - ✓ Connected
postgres: npx -y @modelcontextprotocol/server-postgres - ✓ Connected
github: npx -y @modelcontextprotocol/server-github - ✗ Failed to connect

Xem chi tiết một server cụ thể (bao gồm toàn bộ tool nó cung cấp):

claude mcp get github

Gỡ một server không cần dùng nữa:

claude mcp remove github

Kiểm tra trong session chat

Mở một phiên claude rồi gõ lệnh slash ngay trong chat:

/mcp

Claude sẽ liệt kê tất cả server đang kết nối, trạng thái, số lượng tool/resource/prompt khả dụng từ mỗi server. Đây là bước nên làm đầu tiên mỗi khi mở project mới hoặc sau khi vừa thêm server, để chắc chắn agent thật sự "thấy" được tool bạn kỳ vọng.

Chạy ở chế độ debug khi kết nối thất bại

claude --mcp-debug

Flag này in ra log chi tiết quá trình khởi tạo từng MCP server — request/response handshake, lỗi parse JSON, timeout — thay vì chỉ báo "Failed to connect" chung chung.

Các lỗi thường gặp và cách xử lý

Mẹo: Sau mỗi lần thêm hoặc sửa MCP server, luôn chạy claude mcp list rồi mới /mcp trong session — thói quen này giúp bạn bắt lỗi cấu hình ngay tại chỗ, tránh tình huống giao một task phức tạp cho agent rồi mới phát hiện nó chưa hề gọi được tool nào từ đầu.

Mẹo thực chiến khi làm việc với MCP trong Claude Code CLI

Tổng hợp lại một số kinh nghiệm quan trọng khi cấu hình và duy trì MCP trong Claude Code CLI theo thời gian, không chỉ ở lần setup đầu tiên:

Mẹo: Đừng đăng ký quá nhiều MCP server cùng lúc ở scope global (user). Mỗi server thêm vào đồng nghĩa với việc mô tả (schema) của toàn bộ tool nó cung cấp bị nạp vào context window (cửa sổ ngữ cảnh — phần bộ nhớ ngắn hạn model dùng để xử lý cuộc trò chuyện) ngay từ đầu session, dù bạn không dùng tới. Chỉ bật server thật sự cần cho project đang làm, dùng claude mcp remove dọn dẹp server không còn dùng.

Mẹo: Trước khi thêm một MCP server community lạ (không phải do Anthropic hoặc chính nhà cung cấp dịch vụ phát hành), luôn đọc qua source code của nó — đặc biệt phần xử lý input và gọi lệnh hệ thống. MCP server chạy với quyền của chính bạn trên máy, một server độc hại có thể đọc file, gọi network, hoặc thực thi lệnh tuỳ ý mà không cần khai báo rõ trong tool description.

Mẹo: Với server cần secret (token, API key, connection string), luôn truyền qua biến môi trường (-e hoặc key env trong JSON), tuyệt đối không hardcode thẳng vào args. Lý do đơn giản: args thường bị log ra màn hình hoặc file debug, còn giá trị trong env ít khi bị in ra theo cách tương tự và dễ tách biệt theo từng máy/từng môi trường (dev, staging, production).

Mẹo: Khi làm CI/CD hoặc muốn tái lập chính xác cấu hình MCP trên nhiều máy, ưu tiên claude mcp add-json hoặc commit trực tiếp .mcp.json (không chứa secret) thay vì gõ tay từng lệnh claude mcp add — JSON tường minh, dễ review trong pull request, và không phụ thuộc vào việc ai đó nhớ đúng thứ tự flag.

Mẹo: Đặt tên server có ý nghĩa và nhất quán trong team (ví dụ db-prod-readonly thay vì postgres2) — tên này chính là phần đứng sau mcp__ trong permission key (mcp__db-prod-readonly__query), nên tên rõ ràng giúp việc review file .claude/settings.json sau này dễ hiểu hơn nhiều, đặc biệt khi danh sách server tăng lên theo thời gian.