Kết nối MCP server (quickstart)

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Model Context Protocol (MCP) cho phép Claude Code dùng các tool ngoài bộ tool tích hợp sẵn - như tìm kiếm issue tracker, truy vấn database, hoặc điều khiển trình duyệt. Những tool này đến từ MCP server, chạy trên máy bạn hoặc dưới dạng dịch vụ hosted.

Hướng dẫn này đi qua trọn vẹn việc kết nối một MCP server với Claude Code CLI. Kết thúc bài, bạn sẽ có một server đã kết nối và phản hồi, biết cấu hình của nó nằm ở đâu trên đĩa, và biết cách sửa các lỗi kết nối thường gặp nhất.

Trước khi bắt đầu

Claude Code đã cài đặt và xác thực
Một terminal mở trong thư mục project (bất kỳ thư mục nào, kể cả thư mục rỗng)

Thêm và kiểm tra server

Ví dụ dưới đây kết nối tới MCP server tài liệu Claude Code - một server hosted có full-text search trên tài liệu Claude Code, không cần xác thực hay cấu hình đặc biệt, phù hợp để test luồng thiết lập lần đầu.

Thêm MCP server. Đăng ký server với Claude Code. Chạy lệnh này ở terminal, không phải bên trong một phiên claude - vì bạn đang cấu hình server trước khi bắt đầu hội thoại:
Terminal window
```
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
```
Giải thích các phần:
- claude mcp add: đăng ký một server với Claude Code
- --transport http: server được host tại một URL thay vì chạy như tiến trình local
- claude-code-docs: tên bạn tự đặt - dùng để gán nhãn tool của server trong output của Claude và tham chiếu trong các lệnh như claude mcp remove
- https://code.claude.com/docs/mcp: URL nơi server được host
Lệnh in ra xác nhận kiểu Added HTTP MCP server claude-code-docs..., theo sau bởi dòng File modified: cho biết file cấu hình đã được ghi. local config nghĩa là server được đăng ký riêng cho bạn, chỉ trong project hiện tại. Muốn đăng ký một lần cho mọi project, dùng --scope user (xem Đổi phạm vi server).

Kiểm tra trạng thái kết nối:

claude mcp list

Server xuất hiện kèm chỉ báo trạng thái:

Trạng thái	Ý nghĩa
`✔ Connected`	Sẵn sàng dùng
`! Connected · tools fetch failed`	Server kết nối được nhưng không liệt kê được tool. Chạy `claude mcp get <tên>` để xem chi tiết lỗi
`! Needs authentication`	Server tiếp cận được nhưng cần đăng nhập qua trình duyệt, hoặc token qua `--header`
`✘ Failed to connect`	Server không phản hồi
`✘ Connection error`	Lỗi trong quá trình kết nối
`⏸ Pending approval`	Server ở project scope chưa được bạn duyệt

Một số console Windows cũ (như console mặc định trên Windows 10) không hỗ trợ ký tự Unicode này, sẽ hiện √ và × thay cho ✔ và ✘.

Dùng server. Khởi động phiên và yêu cầu Claude dùng server mới theo tên:
Terminal window
```
claude
```
```
Use the claude-code-docs server to look up what MCP_TIMEOUT does
```
Bạn thường không cần gọi tên server trong prompt - Claude tự chọn tool phù hợp. Gọi tên ở đây chỉ để đảm bảo demo đi qua đúng server mới thay vì một tool khác như web fetch.

Lần đầu Claude gọi server, nó xin quyền dùng tool mới - duyệt để tiếp tục. Tool call trong output của Claude được gắn nhãn tên server, giúp bạn xác nhận câu trả lời đến từ MCP server chứ không phải kiến thức có sẵn của Claude.
Xoá server (tuỳ chọn). Khi thử nghiệm xong:
Terminal window
```
claude mcp remove claude-code-docs
```
Mỗi server đã kết nối chiếm một phần context window vì tên tool và hướng dẫn của server được load vào mỗi phiên. Xoá server không dùng nữa để giải phóng chỗ đó.

Cấu hình server được lưu ở đâu

Lệnh claude mcp add ghi thông tin server vào một file cấu hình. Mặc định đăng ký ở phạm vi local: riêng bạn, chỉ hoạt động trong project hiện tại. Truyền --scope user để đăng ký một lần cho mọi project, hoặc --scope project để chia sẻ với đồng đội.

Tìm cấu hình trên đĩa

Phạm vi	File	Khả dụng cho
`local`	`~/.claude.json`, dưới mục của project này	Chỉ bạn, chỉ project này. Mặc định
`project`	`.mcp.json` ở gốc project	Mọi người clone project
`user`	`~/.claude.json`, dưới key `mcpServers` cấp cao nhất	Chỉ bạn, mọi project

Trên Windows, ~/.claude.json tương ứng %USERPROFILE%\.claude.json. Nếu bạn đặt CLAUDE_CONFIG_DIR, Claude Code đọc .claude.json từ thư mục đó thay vào.

Chạy claude mcp get claude-code-docs để xem phạm vi nào giữ định nghĩa của một server.

Đổi phạm vi server

Phạm vi của server cố định khi thêm, nên đổi phạm vi nghĩa là xoá rồi thêm lại ở phạm vi mới:

claude mcp remove claude-code-docs --scope local

Dùng ở mọi project của bạn:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Chia sẻ với team (ghi vào .mcp.json ở gốc project):

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

Commit .mcp.json vào version control - đồng đội clone repository và khởi động Claude Code sẽ thấy prompt duyệt server, rồi kết nối cho họ.

Thêm server ví dụ khác

Server local (stdio)

Một server stdio local là chương trình Claude Code khởi động như subprocess trên máy bạn, thay vì dịch vụ tiếp cận qua URL. Dùng cho tool cần truy cập tài nguyên local như trình duyệt, filesystem, hoặc database socket.

Playwright MCP server là ví dụ tốt: cho Claude một trình duyệt để điều hướng, click, đọc - không cần tài khoản. Chạy qua npx, cần Node.js 18+.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Khác với ví dụ hosted ở ba điểm: không có --transport (server local mặc định dùng stdio); mọi thứ sau dấu -- là lệnh Claude Code chạy để khởi động server; -y để npx cài package không hỏi.

Kiểm tra kết nối bằng claude mcp list - lần đầu có thể hiện ✘ Failed to connect trong lúc npx tải package, đợi rồi chạy lại.

Server cần đăng nhập (OAuth)

Dịch vụ hosted như Sentry, Linear, Notion chạy MCP server sau OAuth: bạn thêm URL của server, rồi đăng nhập qua trình duyệt.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Sau khi thêm, claude mcp list hiện server với ! Needs authentication. Trong phiên Claude Code, chạy /mcp, chọn sentry, nhấn Enter, chọn Authenticate - trình duyệt mở đến trang đăng nhập của Sentry.

Server xác thực bằng token tĩnh thay vì OAuth nhận token lúc thêm với --header "Authorization: Bearer <token>".

Chỉnh `.mcp.json` trực tiếp

Mọi file trong bảng phạm vi ở trên dùng chung định dạng JSON cho mục server. Phần này chỉnh .mcp.json - file được checkout vào repository, nên đóng vai trò “configuration-as-code” cho team.

Tạo .mcp.json ở gốc project:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Với server HTTP, url là endpoint Claude Code kết nối đến. Với server stdio, command và args là chương trình nó chạy.

Sau khi lưu file, khởi động phiên mới trong project - Claude Code đọc .mcp.json lúc khởi động. Lần đầu thấy một server ở project scope, Claude Code hỏi bạn duyệt - để một repository bạn clone không thể tự khởi chạy tiến trình trên máy bạn mà chưa được đồng ý. Duyệt, hoặc chạy /mcp để duyệt sau nếu bỏ lỡ prompt.

Kết nối từ môi trường khác

Desktop app: thêm server qua Connectors UI
Claude Desktop chat app (app riêng, khác Claude Code): chạy claude mcp add-from-claude-desktop trên macOS/WSL để copy server từ claude_desktop_config.json
VS Code: xem hướng dẫn kết nối MCP của extension VS Code
Claude Code trên web: đọc .mcp.json từ repository của bạn
claude.ai: connector bạn thêm ở claude.ai/customize/connectors tự load trong CLI khi đăng nhập cùng tài khoản

Xử lý sự cố

Nếu server không kết nối được, kiểm tra trạng thái bằng /mcp trong phiên hoặc claude mcp list từ shell, rồi đối chiếu triệu chứng dưới đây.

/mcp hiện “No MCP servers configured”: thường do bạn chạy claude mcp add từ project khác (server local-scope gắn với project lúc thêm), hoặc bạn chỉnh file cấu hình sai đường dẫn - file đúng là ~/.claude.json và <project>/.mcp.json, Claude Code không đọc các đường dẫn như ~/.claude/mcp.json.

Failed to connect hoặc Connection error: server không khởi động hoặc URL không phản hồi. Với server HTTP, kiểm tra URL bằng curl -I <url> - 404/405 nghĩa là server còn sống (nhiều endpoint MCP chỉ trả lời POST); 401/403 nghĩa là cần xác thực. Với server stdio, chạy trực tiếp lệnh đã cấu hình trong terminal để xem lỗi gốc.

Connection timed out at startup: server chạy lâu hơn timeout mặc định 30 giây. Tăng giới hạn bằng biến môi trường MCP_TIMEOUT (mili-giây):

MCP_TIMEOUT=60000 claude

Server already exists: bạn đã thêm server cùng tên ở cùng phạm vi - xoá entry cũ hoặc chọn tên khác.

Server kết nối nhưng không thấy tool nào: chạy /mcp, chọn server để xem danh sách tool. Danh sách rỗng thường do thiếu biến môi trường bắt buộc (ví dụ API key) - truyền bằng --env KEY=value khi claude mcp add.

Thay đổi .mcp.json không có hiệu lực: Claude Code đọc .mcp.json lúc khởi động phiên - thoát và khởi động lại sau khi chỉnh file.

OAuth sign-in fails hoặc trình duyệt không mở: chạy /mcp, chọn server, chọn Authenticate lại. Nếu trình duyệt không tự mở, copy URL hiện trong terminal và mở thủ công.

Bước tiếp theo

Tìm thêm MCP server trong Anthropic Directory
Chia sẻ server với team bằng installation scope
Quản lý MCP access cho tổ chức qua managed settings và policy control
Tham chiếu MCP resource trong prompt bằng @-mention
Chạy MCP prompt như command từ menu /

Phuc Tran

Software Engineer | Learning Claude