Cách cài đặt MCP Server cho Claude Desktop và Claude Code

Cách cài MCP cho Claude phụ thuộc vào ứng dụng bạn đang dùng.

Claude Desktop thường đọc một tệp JSON và tự khởi chạy MCP Server cục bộ. Claude Code cung cấp lệnh claude mcp add, hỗ trợ server cục bộ qua stdio và server từ xa qua HTTP.

Nếu chọn nhầm hướng dẫn, bạn có thể có một tệp JSON hoàn toàn hợp lệ nhưng Claude vẫn không nhận server. Vì vậy, hãy xác định client trước khi sửa cấu hình.

Bạn đang dùng Cách cấu hình chính
Claude Desktop claude_desktop_config.json
Claude Code claude mcp add hoặc .mcp.json
Server cục bộ Transport stdio
Server từ xa Streamable HTTP
Cấu hình cá nhân trong một project Local scope
Chia sẻ cấu hình với đội Project scope
Dùng trong mọi project cá nhân User scope

Hướng dẫn dưới đây được đối chiếu với tài liệu MCP và Claude Code chính thức tại ngày 15/09/2026.

MCP giúp Claude làm được gì?

MCP cho phép Claude kết nối với dữ liệu và công cụ bên ngoài thông qua một giao thức chung.

Sau khi kết nối, Claude có thể:

  • Đọc tệp trong thư mục được cấp quyền.
  • Tìm issue và pull request.
  • Truy vấn database.
  • Gọi API nội bộ.
  • Điều khiển trình duyệt cho tác vụ QA.
  • Lấy dữ liệu web hiện tại.
  • Dùng công cụ quản lý dự án hoặc giám sát hệ thống.

MCP Server cung cấp tool và resource. Claude chọn công cụ dựa trên yêu cầu của người dùng, nhưng server vẫn quyết định hành động nào được phép.

Phân biệt Claude Desktop và Claude Code

Claude Desktop

Claude Desktop là ứng dụng giao diện đồ họa. Với local MCP Server, ứng dụng đọc cấu hình trong claude_desktop_config.json, khởi chạy process và giao tiếp với process qua stdio.

Tệp cấu hình nằm tại:

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Sau khi thay đổi cấu hình, cần thoát hoàn toàn ứng dụng rồi mở lại. Chỉ đóng cửa sổ có thể chưa dừng process Claude Desktop.

Claude Code

Claude Code chạy trong terminal và có lệnh riêng để quản lý MCP:

claude mcp add
claude mcp list
claude mcp get
claude mcp remove

Claude Code còn có ba scope để quyết định server xuất hiện ở đâu: local, project và user.

Điều kiện trước khi cài đặt

Với MCP Server chạy bằng Node.js, hãy kiểm tra:

node --version
npm --version
npx --version

Nếu server dùng Python, kiểm tra:

python --version

Một số package sử dụng uvx:

uvx --version

Bạn cũng cần:

  • Claude Desktop hoặc Claude Code đã được cài đặt.
  • Lệnh khởi chạy hoặc URL chính xác của MCP Server.
  • Token, API key hoặc thông tin đăng nhập nếu server yêu cầu.
  • Danh sách thư mục và tài nguyên mà server được phép truy cập.

Không cài package chỉ dựa trên tên gần giống. Hãy lấy lệnh từ repository chính thức của server hoặc từ Official MCP Registry.

Cách 1: Cài local MCP Server cho Claude Desktop

Ví dụ dưới đây sử dụng Filesystem Server để Claude truy cập một thư mục cụ thể.

Bước 1: Tạo thư mục thử nghiệm

Ví dụ trên Windows:

C:\MCP-Data

Chỉ đặt dữ liệu thử nghiệm vào thư mục này. Không cấp toàn bộ thư mục người dùng hoặc ổ đĩa trong lần cấu hình đầu.

Bước 2: Mở tệp cấu hình

Trong Claude Desktop, mở phần Settings, chọn Developer rồi chọn Edit Config.

Nếu mở thủ công, dùng đường dẫn:

%APPDATA%\Claude\claude_desktop_config.json

Bước 3: Thêm cấu hình trên Windows

Repository MCP chính thức hướng dẫn bọc npx bằng cmd /c trên Windows:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\MCP-Data"
      ]
    }
  }
}

Dấu gạch chéo ngược trong JSON phải được viết thành \\. Nếu nhập C:\MCP-Data, tệp có thể không còn là JSON hợp lệ.

Bước 4: Cấu hình trên macOS

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/MCP-Data"
      ]
    }
  }
}

Thay username và đường dẫn bằng giá trị trên máy của bạn.

Bước 5: Khởi động lại Claude Desktop

Lưu tệp, thoát hoàn toàn Claude Desktop rồi mở lại.

Vào Settings, Developer hoặc phần quản lý connectors để kiểm tra server filesystem. Nếu server hoạt động, Claude sẽ hiển thị các tool do server cung cấp.

Bước 6: Chạy yêu cầu thử

Dùng một yêu cầu chỉ đọc:

Liệt kê tên các tệp trong thư mục được cấp quyền. Không tạo, sửa, đổi tên hoặc xóa tệp.

Nếu Claude trả đúng danh sách và yêu cầu phê duyệt khi cần, kết nối đã hoạt động.

Tài liệu MCP chính thức cũng dùng Filesystem Server để minh họa kết nối local server với Claude Desktop. Xem hướng dẫn kết nối local MCP Server.

Thêm nhiều MCP Server vào cùng tệp JSON

Mỗi server là một phần tử bên trong mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\MCP-Data"
      ]
    },
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

Các phần tử ngang hàng phải được ngăn bằng dấu phẩy. Không thêm dấu phẩy sau phần tử cuối cùng.

Mỗi server chạy thành một process riêng. Việc thêm nhiều server có thể làm tăng thời gian khởi động và số tool Claude phải xử lý. Chỉ bật server cần cho công việc hiện tại.

Cách 2: Cài MCP Server từ xa cho Claude Code

Streamable HTTP là lựa chọn được khuyến nghị cho server cloud. Cú pháp cơ bản:

claude mcp add --transport http ten-server https://mcp.example.com/mcp

Ví dụ sử dụng tên web-data:

claude mcp add --transport http web-data https://mcp.example.com/mcp

URL trên chỉ là minh họa. Hãy dùng endpoint do nhà cung cấp server công bố.

Sau khi thêm, kiểm tra:

claude mcp get web-data
claude mcp list

Tài liệu Claude Code hiện khuyến nghị HTTP cho server từ xa. SSE đã bị đánh dấu deprecated và chỉ nên được giữ cho server cũ chưa hỗ trợ transport mới. Xem tài liệu MCP của Claude Code.

Cách 3: Cài local stdio MCP Server cho Claude Code

Với server chạy bằng npx, đặt toàn bộ lệnh khởi chạy sau dấu --:

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem C:\MCP-Data

Dấu -- ngăn Claude Code đọc nhầm tham số của server thành tham số của chính lệnh claude.

Nếu server cần biến môi trường:

claude mcp add \
  --transport stdio \
  --env API_KEY=your-key \
  example \
  -- npx -y @example/mcp-server

@example/mcp-server là tên minh họa. Không sao chép nguyên lệnh này để cài đặt.

Trên PowerShell, bạn có thể viết lệnh trên một dòng để tránh khác biệt về ký tự nối dòng:

claude mcp add --transport stdio --env API_KEY=your-key example -- npx -y @example/mcp-server

Không lưu token thật vào tài liệu, ảnh chụp màn hình hoặc repository.

Chọn đúng scope trong Claude Code

Local scope

Local là scope mặc định. Server chỉ xuất hiện trong project nơi bạn thêm nó và cấu hình vẫn thuộc về người dùng hiện tại.

claude mcp add --scope local --transport http internal-api https://mcp.example.com/mcp

Local phù hợp với server thử nghiệm, cấu hình cá nhân hoặc server chứa thông tin xác thực không nên đưa vào Git.

Project scope

Project scope lưu cấu hình trong .mcp.json tại thư mục gốc của project:

claude mcp add --scope project --transport http shared-server https://mcp.example.com/mcp

Tệp này có thể được commit để cả đội dùng cùng cấu hình. Không đặt token thật trực tiếp trong .mcp.json.

Khi mở một repository có MCP Server ở project scope, Claude Code có thể yêu cầu phê duyệt. Hãy kiểm tra cấu hình trước khi chấp nhận. Repository không được tự phê duyệt server của chính nó.

User scope

User scope cho phép sử dụng server trong nhiều project của cùng người dùng:

claude mcp add --scope user --transport http personal-tools https://mcp.example.com/mcp

Scope này phù hợp với công cụ cá nhân mà bạn dùng thường xuyên. Không nên dùng user scope cho server chỉ liên quan đến một khách hàng hoặc một repository.

Cài từ một khối JSON có sẵn

Nếu tài liệu của nhà cung cấp chỉ đưa cấu hình dành cho Claude Desktop, Claude Code có thể nhập phần server bằng add-json.

Cấu hình ban đầu:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

Lệnh tương ứng:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Chỉ truyền object nằm bên trong mcpServers, không truyền toàn bộ wrapper.

Với server từ xa, cấu hình phải có type:

{
  "type": "http",
  "url": "https://mcp.example.com/mcp"
}

Một object có url nhưng thiếu type có thể bị Claude Code hiểu như stdio server và kết nối thất bại.

Cấu hình MCP cho quy trình thu thập dữ liệu web

Web Data MCP Server thường cung cấp tool để đọc URL, tìm kiếm hoặc trả nội dung có cấu trúc.

Luồng xử lý có thể gồm:

  1. Claude gọi tool với URL và yêu cầu dữ liệu.
  2. MCP Server kiểm tra tham số.
  3. Server gửi request đến website hoặc scraping API.
  4. Dữ liệu được làm sạch thành Markdown hoặc JSON.
  5. Claude phân tích kết quả và trả lời người dùng.

Với trang JavaScript, server có thể cần browser automation. Những trang cuộn vô hạn còn cần điều kiện chờ và điều kiện dừng rõ ràng. Có thể tham khảo hướng dẫn thu thập dữ liệu trang infinite scroll bằng Puppeteer.

Nếu hệ thống cần kiểm tra nội dung công khai theo quốc gia hoặc thành phố, proxy có thể được đặt ở lớp HTTP hoặc browser phía sau MCP Server. Bài Proxy Datacenter và ISP Targeting giải thích sự khác nhau giữa country, city và ASN targeting.

MCP không làm thay đổi quyền truy cập của crawler. Server vẫn phải tuân thủ điều khoản website, giới hạn request và quy định về dữ liệu.

Cách quản lý API key an toàn

Không ghi token trực tiếp vào repository

Tệp .mcp.json ở project scope có thể được commit. Vì vậy, không đặt token thật trong tệp này.

Ưu tiên:

  • Biến môi trường.
  • Secret manager.
  • OAuth nếu server hỗ trợ.
  • Tài khoản dịch vụ riêng.
  • Token có thời hạn và phạm vi hẹp.

Không đưa secret vào câu lệnh chia sẻ

Lệnh terminal có thể được lưu trong shell history. Không đăng ảnh chụp lệnh có token lên ticket hoặc kênh chat.

Nếu token bị lộ, hãy thu hồi và tạo token mới. Xóa nội dung khỏi Git không đủ vì giá trị cũ có thể còn trong lịch sử commit.

Tách quyền đọc và quyền ghi

Database nên dùng tài khoản chỉ đọc cho tác vụ phân tích. GitHub token chỉ nên truy cập đúng repository cần thiết. Server file chỉ nên nhận những thư mục mà quy trình thực sự dùng.

Giữ bước phê duyệt cho hành động bên ngoài

Đọc file và gửi email là hai mức rủi ro khác nhau. Các tool có thể gửi tin nhắn, cập nhật dữ liệu hoặc tạo giao dịch cần bước xác nhận riêng.

Kiểm tra kết nối trong Claude Code

Liệt kê server:

claude mcp list

Xem chi tiết một server:

claude mcp get filesystem

Kiểm tra trong phiên Claude Code:

/mcp

Xóa server:

claude mcp remove filesystem

Các trạng thái thường gặp gồm:

  • Connected: Server đã kết nối.
  • Needs authentication: Server cần đăng nhập hoặc token.
  • Failed to connect: Claude Code đã đọc cấu hình nhưng không thể kết nối.
  • Pending approval: Server ở project scope đang chờ người dùng duyệt.
  • Disabled: Server đã bị tắt trong project hiện tại.

Dòng thông báo server đã được thêm chỉ xác nhận cấu hình được ghi. Nó chưa chứng minh tool có thể chạy thành công.

Các lỗi Claude MCP thường gặp

Claude Desktop không hiển thị server

Kiểm tra lần lượt:

  1. Đã thoát hoàn toàn Claude Desktop chưa.
  2. Tệp có đúng tên claude_desktop_config.json không.
  3. JSON có thiếu dấu phẩy hoặc ngoặc đóng không.
  4. Đường dẫn Windows đã dùng \\ chưa.
  5. Lệnh node, npx hoặc uvx có chạy trong terminal không.
  6. Package có tồn tại và đúng tên không.

Lỗi npx hoặc command not found

Chạy:

node --version
npm --version
npx --version

Nếu terminal nhận lệnh nhưng Claude Desktop không nhận, ứng dụng có thể chưa đọc PATH mới. Khởi động lại ứng dụng hoặc máy sau khi cài Node.js.

Trên Windows, một số cấu hình cần dùng:

"command": "cmd",
"args": ["/c", "npx", "-y", "package-name"]

Server kết nối rồi ngắt ngay

Chạy thủ công lệnh nằm trong command và args. Nếu process thoát, terminal thường hiển thị lỗi rõ hơn Claude Desktop.

Nguyên nhân phổ biến:

  • Thiếu biến môi trường.
  • Token không hợp lệ.
  • Sai đường dẫn.
  • Dependency chưa được cài.
  • Port đang được process khác sử dụng.
  • Server ghi dữ liệu không đúng kênh khi dùng stdio.

Failed to connect trong Claude Code

Kiểm tra:

claude mcp get ten-server

Với HTTP server, xác nhận URL và phương thức xác thực. Với stdio server, chạy riêng lệnh sau dấu --.

Nếu cấu hình có cả url và object JSON, kiểm tra trường "type": "http".

Server ở trạng thái Pending approval

Khởi chạy Claude Code trong project:

claude

Đọc cấu hình được hiển thị rồi phê duyệt nếu bạn tin cậy server. Không tìm cách bỏ qua cảnh báo đối với repository vừa tải từ Internet.

Tool xuất hiện nhưng gọi thất bại

Kết nối MCP chỉ chứng minh client nhìn thấy server. Tool vẫn có thể lỗi do:

  • Schema đầu vào không đúng.
  • Tài khoản không đủ quyền.
  • API bên ngoài trả 401, 403 hoặc 429.
  • Server không xử lý timeout.
  • Website thay đổi cấu trúc.
  • Proxy hoặc DNS không kết nối được.

Nếu Web Data MCP Server dùng proxy, hãy kiểm tra IP độc lập bằng Proxy Checker trước khi sửa logic của tool.

MCP web data liên tục gặp CAPTCHA

Giảm concurrency và kiểm tra lại tần suất request. Không retry vô hạn và không đổi IP chỉ để phớt lờ mã 429.

Bài cách xử lý CAPTCHA khi web scraping trình bày quy trình kiểm tra điều khoản, rate limit và nguồn dữ liệu thay thế trước khi tiếp tục.

Checklist bảo mật trước khi dùng MCP Server

  • Xác minh nhà phát hành và repository.
  • Đọc danh sách tool trước khi kết nối.
  • Kiểm tra script cài đặt và dependency.
  • Chỉ cấp thư mục cần thiết.
  • Dùng tài khoản database chỉ đọc.
  • Giới hạn token theo repository hoặc workspace.
  • Không commit secret vào .mcp.json.
  • Không đưa token vào log.
  • Giữ bước phê duyệt cho hành động ghi.
  • Kiểm tra dữ liệu trả về từ website vì có rủi ro prompt injection.
  • Tắt server không dùng.
  • Thu hồi token khi xóa tích hợp.
  • Kiểm tra log sau lần chạy đầu tiên.

Anthropic cảnh báo rằng server lấy nội dung bên ngoài có thể đưa prompt injection vào context. Vì vậy, không nên xem nội dung do tool trả về là chỉ dẫn đáng tin cậy. Xem tài liệu MCP chính thức của Claude Code.

Câu hỏi thường gặp

Claude Desktop có tự cài MCP Server không?

Claude Desktop có thể tự khởi chạy một local server đã được khai báo trong tệp cấu hình. Package vẫn phải tồn tại hoặc có thể được trình quản lý package như npx tải xuống.

Có cần mở terminal khi dùng MCP trên Claude Desktop không?

Không nhất thiết. Claude Desktop có thể tự chạy process. Terminal hữu ích khi cần kiểm tra lệnh hoặc xem lỗi khởi động.

Nên dùng HTTP hay stdio?

Stdio phù hợp với server chạy cục bộ. Streamable HTTP phù hợp với server từ xa. SSE là transport cũ và đã bị deprecated trong tài liệu Claude Code.

.mcp.json khác claude_desktop_config.json thế nào?

.mcp.json thường được Claude Code dùng cho cấu hình theo project. claude_desktop_config.json là tệp cấu hình local server của Claude Desktop.

Cài xong nhưng Claude không tự dùng tool thì làm gì?

Hãy viết yêu cầu chỉ rõ mục tiêu và server cần dùng, ví dụ:

Dùng tool filesystem để liệt kê các tệp Markdown trong thư mục được cấp quyền. Không thay đổi tệp.

Nếu cách này hoạt động, kết nối không có lỗi. Vấn đề nằm ở việc mô hình chưa chọn tool khi prompt còn mơ hồ.

Có thể dùng proxy với MCP Server không?

Có, nếu server gọi HTTP hoặc điều khiển browser. Proxy được cấu hình ở lớp server hoặc thư viện mạng, không phải trong giao thức MCP. Bạn có thể đọc rotating proxy hoạt động như thế nào trước khi chọn cơ chế đổi IP hoặc giữ phiên.

Kết luận

Với Claude Desktop, hãy bắt đầu bằng một local Filesystem Server và chỉ cấp một thư mục thử nghiệm. Với Claude Code, dùng claude mcp add, chọn đúng transport và scope, sau đó kiểm tra bằng claude mcp list.

Một cấu hình tốt cần trả lời rõ server chạy ở đâu, được phép truy cập gì và hành động nào cần người dùng xác nhận. Nếu ba điểm này chưa rõ, chưa nên bật server cho dữ liệu production.

© 2026 Proxify.vn. All rights reserved.

Bảo mật · An toàn · Tự động