Hướng Dẫn

Hướng dẫn thiết lập Claude Code MCP: Tối ưu AI Coding Agent

Việt Trần
Việt Trần
Đăng ngày
Hướng dẫn thiết lập Claude Code MCP: Tối ưu AI Coding Agent

Claude Code MCP là cách Claude Code sử dụng Model Context Protocol để kết nối trực tiếp với cơ sở dữ liệu, hệ thống file và dịch vụ bên ngoài thông qua các MCP server. Bài viết này hướng dẫn bạn cấu hình Claude Code MCP từ cơ bản đến thực tế, bao gồm thiết lập server, chỉnh file cấu hình và kiểm tra hoạt động ngay trong môi trường làm việc.

Những điểm chính

  • Khái niệm MCP: Hiểu rõ Model Context Protocol là tiêu chuẩn kết nối, đóng vai trò giúp Claude Code giao tiếp trực tiếp với cơ sở dữ liệu, file hệ thống và các dịch vụ bên ngoài mà không cần sửa đổi mã nguồn lõi.
  • Cơ chế hoạt động: Nắm được cách Claude Code tự động phát hiện và gọi các công cụ từ MCP Server, giúp bạn truy vấn dữ liệu hoặc gọi API ngay trong phiên làm việc một cách liền mạch.
  • Hướng dẫn thiết lập: Biết cách cài đặt MCP Server thông qua 2 phương pháp: Dùng trình hướng dẫn CLI và cấu hình thủ công bằng file JSON.
  • Cấu trúc file JSON: Nắm vững cú pháp của file .claude.json với các trường quan trọng như command, args và env.
  • Kiểm tra và xử lý lỗi: Bỏ túi quy trình quản lý trạng thái Server bằng lệnh /mcp và các bước khắc phục lỗi cơ bản khi cấu hình bị crash.
  • Ứng dụng thực tiễn: Khám phá sức mạnh của các MCP Server phổ biến như Playwright , Postgres, Filesystem và GitHub.
  • Câu hỏi thường gặp: Được giải đáp các thắc mắc về cách MCP Server tiêu thụ tài nguyên, khả năng cấu hình riêng cho từng dự án và tính an toàn của dữ liệu khi truyền tải.

Model Context Protocol là gì?

Model Context Protocol (MCP) là một tiêu chuẩn mở dùng để kết nối các ứng dụng AI với dữ liệu và công cụ bên ngoài. Trong ngữ cảnh Claude Code, MCP hoạt động như lớp cầu nối giữa mô hình và các nguồn dữ liệu hoặc công cụ cục bộ, cho phép kết nối tới cơ sở dữ liệu, công cụ tìm kiếm hoặc trình duyệt web mà không cần sửa đổi mã nguồn lõi.

BlockNote image

Trong Claude Code, MCP hoạt động như lớp cầu nối giữa mô hình và các nguồn dữ liệu

Claude Code MCP hoạt động như thế nào?

Claude Code MCP là cách Claude Code sử dụng Model Context Protocol để kết nối với cơ sở dữ liệu, hệ thống file và các dịch vụ bên ngoài thông qua các MCP server được khai báo trong cấu hình. Khi bạn thêm một MCP server, Claude Code tự động phát hiện các tool mà server đó cung cấp và có thể gọi chúng trực tiếp trong phiên làm việc để truy vấn dữ liệu, thao tác file hoặc gọi API mà không cần viết thêm mã tích hợp thủ công.

Thiết lập MCP servers trong Claude Code

Bạn có thể thiết lập MCP servers theo hai cách tương ứng với hai mức độ quen thuộc về kỹ thuật:

Cách 1: Thiết lập bằng CLI wizard

Cách này phù hợp khi bạn muốn kết nối MCP server nhanh mà không cần hiểu ngay cấu trúc file cấu hình.

Bước 1: Mở terminal hoặc command prompt trên máy tính và chuyển đến thư mục dự án mà bạn đang dùng với Claude Code.

Bước 2: Nhập lệnh: claude mcp add. Lệnh này sẽ mở một trình hướng dẫn tương tác trong terminal.

Bước 3: Chọn một MCP server có sẵn từ danh sách gợi ý hoặc dán lệnh cài đặt server (ví dụ: npx -y @modelcontextprotocol/server-postgresql).

Bước 4: Trình hướng dẫn sẽ lần lượt hỏi các thông tin cần thiết, ví dụ:

  • API key hoặc token truy cập.
  • Địa chỉ cơ sở dữ liệu hoặc URL kết nối.
  • Tên server hoặc nhãn để nhận diện trong Claude Code.

Bước 5: Sau khi hoàn thành các bước, CLI sẽ cập nhật cấu hình giúp Claude Code nhận diện và hiển thị MCP server mới trong danh sách công cụ. Bạn có thể mở Claude Code và kiểm tra trong phần Tools hoặc MCP để xác nhận server đã kết nối thành công.

BlockNote image

Quy trình thiết lập MCP servers bằng CLI wizard

Cách 2: Cấu hình thủ công bằng file cấu hình

Cách này phù hợp khi bạn cần kiểm soát chi tiết, triển khai trên nhiều máy hoặc muốn đưa cấu hình vào Git để chia sẻ với cả nhóm.

Bước 1: Xác định vị trí file cấu hình: Claude Code thường sử dụng một file cấu hình JSON trong thư mục người dùng, ví dụ: ~/.claude.json. Hoặc một file cấu hình tương đương được tài liệu Claude chỉ định.

Bước 2: Mở file bằng trình soạn thảo: Dùng VS Code, Claude Code hoặc bất kỳ editor nào để mở file này. Nội dung sẽ ở dạng JSON gồm danh sách MCP servers và các tham số kết nối.

Bước 3: Thêm cấu hình MCP server mới: Bạn thêm một mục mới mô tả server, bao gồm các phần chính như:

  • Tên server để hiển thị.
  • Lệnh khởi chạy server hoặc đường dẫn tới binary.
  • Biến môi trường cần thiết như API key hoặc URL.

Bước 4: Lưu file và khởi động lại Claude Code: Sau khi chỉnh sửa, lưu file cấu hình rồi khởi động lại Claude Code để hệ thống nạp thiết lập mới. MCP server vừa thêm sẽ xuất hiện trong danh sách server mà Claude có thể sử dụng.

BlockNote image

Quy trình thiết lập MCP servers thủ công bằng file cấu hình

Kiểu kết nối và phạm vi cấu hình MCP

MCP server có thể giao tiếp với Claude Code qua hai cơ chế chính là stdio (tiến trình cục bộ) và HTTP (dịch vụ từ xa hoặc container). Khi dùng lệnh claude mcp add, bạn có thể chọn kiểu kết nối phù hợp, trong đó stdio thường dùng với lệnh npx hoặc node, còn HTTP phù hợp cho các dịch vụ chạy qua URL cố định.

Claude Code hỗ trợ nhiều phạm vi cấu hình MCP, bao gồm file cấu hình người dùng như ~/.claude.json và file cấu hình theo dự án như .mcp.json đặt trong thư mục project. Khi tồn tại nhiều cấu hình trùng tên server, cấu hình ở mức dự án sẽ được ưu tiên hơn cấu hình chung của người dùng, giúp bạn chia sẻ thiết lập chuẩn trong team mà không ảnh hưởng đến môi trường cá nhân.

Cấu trúc và cú pháp file cấu hình .claude.json

File .claude.json lưu cấu hình MCP servers dưới dạng đối tượng JSON, trong đó mỗi server được khai báo với lệnh chạy, danh sách đối số và biến môi trường cần thiết. Khi dùng npx, hệ thống sẽ tải và chạy phiên bản gói MCP server mới nhất mà không cần cài đặt cố định trong dự án.

{
  "mcpServers": {
    "my-postgres-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://user:pass@localhost:5432/db"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/db"
      }
    }
  }
}
  • command: Lệnh dùng để khởi chạy server, thường npx hoặc node tùy cách phân phối MCP server.
  • args: Danh sách đối số truyền cho lệnh, bao gồm tên gói MCP server và chuỗi kết nối hoặc tham số cần thiết.
  • env: Nơi khai báo các biến môi trường như URL cơ sở dữ liệu hoặc API key, nên dùng cho thông tin nhạy cảm thay vì ghi trực tiếp trong args.
  • Bảo mật: Không nên đưa .claude.json chứa thông tin nhạy cảm lên kho Git công khai, nên thêm file này hoặc thư mục .claude/vào .gitignore và ưu tiên quản lý API key thông qua biến môi trường hoặc giải pháp quản lý bí mật an toàn.

Quản lý và kiểm tra tình trạng MCP Servers

Để kiểm tra xem các server đã được kết nối thành công chưa, hãy thực hiện theo quy trình sau:

Sử dụng lệnh /mcp: Gõ lệnh này ngay trong phiên làm việc của Claude Code để xem danh sách các server đang chạy và các tool khả dụng.

Xử lý lỗi:

  • Kiểm tra lại đường dẫn file script hoặc cấu hình npx trong file .claude.json.
  • Đảm bảo các biến môi trường (env) đã được cấp quyền truy cập cần thiết.
  • Xem logs trong terminal để biết chính xác server bị crash ở đâu.

Reload: Sau khi sửa file cấu hình, hãy khởi động lại Claude Code để các thay đổi có hiệu lực.

BlockNote image

Sử dụng lệnh /mcp liệt kê các công cụ khả dụng sau khi cấu hình thành công

Ứng dụng thực tế: Các MCP Servers phổ biến

Dưới đây là một số MCP servers được sử dụng nhiều trong các dự án phát triển với Claude Code và các client hỗ trợ MCP. Mỗi server mở rộng khả năng của mô hình theo một hướng cụ thể như tự động hóa trình duyệt, truy vấn cơ sở dữ liệu hoặc thao tác với mã nguồn.

  • Playwright MCP: Cho phép mô hình điều khiển trình duyệt, điều hướng trang, tương tác với phần tử, thực hiện kiểm thử giao diện và chụp ảnh màn hình cho các tác vụ web tự động.
  • Postgres MCP: Cho phép kết nối trực tiếp tới cơ sở dữ liệu PostgreSQL, khám phá schema và thực thi truy vấn SQL an toàn từ trong môi trường làm việc với Claude.
  • Filesystem MCP: Cung cấp khả năng đọc và ghi tệp trong các thư mục được cho phép, giúp mô hình xem nội dung file mã nguồn, tạo file mới hoặc cập nhật tài liệu trong phạm vi cấu hình cho phép.
  • GitHub MCP: Tích hợp với GitHub để truy cập repository, liệt kê và cập nhật issues, đọc hoặc tạo pull request và thực hiện một số thao tác quản lý mã từ xa thông qua API GitHub.

BlockNote image

Một số MCP servers được sử dụng phổ biến trong các dự án phát triển với Claude Code

Giải đáp thắc mắc thường gặp

MCP Server có chạy ngầm không?

MCP server chỉ chạy khi Claude Code hoặc phiên làm việc hiện tại gọi tới công cụ tương ứng, sau đó có thể dừng lại khi không còn yêu cầu để tiết kiệm tài nguyên.

Tôi có thể cấu hình MCP theo từng dự án không?

Bạn có thể cấu hình theo dự án thông qua file như .claude.json trong thư mục project và Claude Code sẽ ưu tiên cấu hình ở phạm vi dự án hơn cấu hình chung của người dùng khi tên server trùng nhau.

Dữ liệu của tôi có bị gửi ra ngoài không?

Với MCP server chạy cục bộ như Postgres hoặc Filesystem, dữ liệu được xử lý trong môi trường máy của bạn, còn với server kết nối dịch vụ ngoài như GitHub hoặc API bên thứ ba, dữ liệu sẽ được gửi qua giao thức MCP tới dịch vụ đó để xử lý theo phạm vi quyền bạn đã cấp.

Tại sao lệnh tôi dùng không nhận diện được MCP?

Bạn cần kiểm tra lại cấu hình và trạng thái server bằng lệnh /mcp hoặc claude mcp list, đồng thời đảm bảo tên server đúng, file JSON không lỗi cú pháp và biến môi trường cần thiết đã được thiết lập.

Xem thêm:

Khi thiết lập đúng Claude Code MCP, bạn có thể biến môi trường soạn thảo mã thành một trung tâm điều phối có khả năng truy vấn dữ liệu, gọi API và thao tác với codebase thông qua các MCP server an toàn. Việc hiểu rõ cách cấu hình, ưu tiên phạm vi dự án và sử dụng các lệnh kiểm tra giúp bạn vận hành Claude Code MCP ổn định trong quy trình phát triển phần mềm hàng ngày.

← Quay lại Blog