jvinhit//lab

Search posts

Type to search across journal entries.

↑ ↓ navigate ↵ open esc close

Claude Code từ zero đến thành thạo · Phần 14 — MCP: nối Claude vào công cụ ngoài

Bốn transport để thêm MCP server, ba scope cài đặt và thứ tự ưu tiên, mở rộng biến môi trường trong .mcp.json, xác thực OAuth, tool search giữ context thấp, và tham chiếu resource bằng @.

12 MIN READ

Model Context Protocol (MCP) là chuẩn mã nguồn mở cho việc tích hợp AI với công cụ. MCP server cấp cho Claude Code quyền truy cập tool, database và API của bạn.

Dấu hiệu nên nối một server rất cụ thể: bạn thấy mình đang copy dữ liệu từ một công cụ khác vào chat — một issue tracker, một dashboard monitoring. Nối rồi thì Claude đọc và hành động trực tiếp trên hệ thống đó thay vì làm việc với thứ bạn dán vào.

Nối rồi thì làm được gì

  • Hiện thực feature từ issue tracker — “Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub.”
  • Phân tích dữ liệu monitoring — “Check Sentry and Statsig to check the usage of the feature described in ENG-4521.”
  • Truy vấn database — “Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database.”
  • Tích hợp thiết kế — “Update our standard email template based on the new Figma designs that were posted in Slack.”
  • Tự động hoá workflow — “Create Gmail drafts inviting these 10 users to a feedback session about the new feature.”
  • Phản ứng với sự kiện bên ngoài — một MCP server còn hoạt động như một channel đẩy tin nhắn vào phiên của bạn, để Claude phản ứng với tin Telegram, chat Discord, hoặc webhook trong lúc bạn đi vắng.

Duyệt các connector đã được review ở Anthropic Directory. Connector trong Directory dùng cùng hạ tầng MCP như Claude Code, nên bạn thêm được bất kỳ remote server nào liệt kê ở đó bằng claude mcp add.

Hãy xác minh bạn tin server trước khi nối nó. Server tải nội dung bên ngoài có thể khiến bạn hứng prompt injection. Đây là rủi ro bảo mật thật, không phải cảnh báo hình thức.

Bốn cách thêm server

1. Remote HTTP server

Đây là lựa chọn được khuyến nghị cho remote server — transport được hỗ trợ rộng nhất cho dịch vụ trên cloud.

# Cú pháp cơ bản
claude mcp add --transport http <name> <url>

# Ví dụ thật: nối Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Ví dụ có Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Khi cấu hình bằng JSON, trường type nhận streamable-http làm alias của http — vì spec MCP dùng tên đó, nên cấu hình copy từ tài liệu của server chạy được mà không cần sửa.

Một lỗi cấu hình hay gặp: một entry JSON có url nhưng không có type là lỗi, vì Claude Code đọc entry không có type là một stdio server. Nó bỏ qua server đó và báo MCP server "<name>" has a "url" but no "type".

2. Remote SSE server

Transport SSE đã deprecated. Dùng HTTP server ở nơi nào có thể.

Một số dịch vụ vẫn chỉ phơi ra endpoint SSE:

claude mcp add --transport sse asana https://mcp.asana.com/sse

# Ví dụ có header xác thực
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

3. Local stdio server

Stdio server chạy như tiến trình cục bộ trên máy bạn. Chúng lý tưởng cho tool cần truy cập hệ thống trực tiếp hoặc script tuỳ biến.

# Cú pháp cơ bản
claude mcp add [options] <name> -- <command> [args...]

# Ví dụ thật: thêm Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Quan trọng — phải phân tách tham số của server bằng --. Dấu gạch nối đôi tách các option của chính Claude (--transport, --env, --scope) khỏi lệnh và tham số chạy server. Mọi thứ sau -- được truyền cho server nguyên vẹn.

Không có --, Claude Code sẽ cố parse flag của server, ví dụ --port, như option của chính nó.

Thêm một bẫy nhỏ: --env nhận nhiều cặp KEY=value. Nếu tên server nằm ngay sau --env, CLI đọc tên đó thành một cặp nữa rồi từ chối — nên hãy đặt ít nhất một option khác giữa --env và tên server.

Claude Code đặt CLAUDE_PROJECT_DIR trong môi trường của server được sinh ra, trỏ tới gốc project — cùng thư mục mà hook nhận được. Đọc nó từ trong tiến trình server của bạn, ví dụ process.env.CLAUDE_PROJECT_DIR trong Node hoặc os.environ["CLAUDE_PROJECT_DIR"] trong Python.

CLAUDE_PROJECT_DIR là gốc project ổn định và không đổi khi bạn thêm/bớt thư mục làm việc giữa phiên. Một server muốn tự giới hạn quyền truy cập filesystem của mình vào một tập thư mục cho phép thì nên hiện thực request MCP roots/list thay vì dùng biến này.

4. Remote WebSocket server

WebSocket giữ kết nối hai chiều liên tục, phù hợp cho remote server chủ động đẩy sự kiện tới Claude. Dùng HTTP thay thế khi server của bạn chỉ phản hồi request, vì HTTP hỗ trợ OAuth và flag claude mcp add --transport, còn WebSocket không hỗ trợ cả hai.

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Xác thực của WebSocket chỉ qua header.

Quản lý server

# Liệt kê mọi server đã cấu hình
claude mcp list

# Xem chi tiết một server
claude mcp get notion

# Xoá một server
claude mcp remove notion

Và trong Claude Code thì dùng /mcp để xem trạng thái.

claude mcp add xác nhận thêm thành công bằng dòng Added ..., nghĩa là cấu hình đã được ghi. Sau đó claude mcp list hiện trạng thái sức khoẻ cạnh mỗi server: ✔ Connected, ! Needs authentication, hoặc ✘ Failed to connect. Trạng thái fail nghĩa là Claude Code không nối được tới server đó, không phải lệnh list bị lỗi.

Server scope project từ .mcp.json đang chờ bạn duyệt hiện dưới dạng ⏸ Pending approval. WebSocket server không xuất hiện trong output của claude mcp list — dùng claude mcp get <name> hoặc panel /mcp để kiểm tra chúng.

Ba scope cài đặt

Scope bạn chọn quyết định server nạp ở project nào và cấu hình có chia sẻ với team hay không.

ScopeNạp ởChia sẻ với teamLưu ở
LocalChỉ project hiện tạiKhông~/.claude.json
ProjectChỉ project hiện tạiCó, qua version control.mcp.json ở gốc project
UserMọi project của bạnKhông~/.claude.json

Local là mặc định. Server scope local chỉ nạp ở project bạn thêm nó và riêng tư với bạn. Claude Code lưu nó trong ~/.claude.json dưới path của project đó, nên cùng server sẽ không xuất hiện ở project khác của bạn.

Thuật ngữ “local scope” cho MCP server khác local settings nói chung: MCP local-scoped server lưu ở ~/.claude.json trong thư mục home, còn local settings nói chung dùng .claude/settings.local.json trong thư mục project.

claude mcp add --transport http stripe https://mcp.stripe.com                  # local (mặc định)
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Project scope lưu cấu hình vào .mcp.json ở gốc project, theo định dạng chuẩn hoá:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Commit .mcp.json vào version control để cả team có cùng bộ MCP tool.

Vì lý do bảo mật, Claude Code hỏi duyệt trong phiên tương tác trước khi dùng server scope project từ .mcp.json. Reset các lựa chọn duyệt đó bằng claude mcp reset-project-choices.

Nhưng claude -p, phiên Agent SDK và phiên cloud không hiện được prompt đó: Claude Code nạp server scope project ở đó mà không hỏi. Muốn giữ một server ở ngoài bất chấp, thêm nó vào disabledMcpjsonServers — cái này chặn nó ở mọi mode.

Thứ tự ưu tiên

Khi cùng một server được khai ở nhiều chỗ, Claude Code nối tới nó một lần, dùng định nghĩa từ nguồn có ưu tiên cao nhất. Toàn bộ entry từ nguồn đó được dùng — các trường không được gộp giữa các scope.

  1. Local scope
  2. Project scope
  3. User scope
  4. Server do plugin cung cấp
  5. Connector từ claude.ai

Ba scope đầu khớp bản trùng theo tên. Plugin và connector khớp theo endpoint, nên một cái trỏ tới cùng URL hoặc cùng lệnh với server phía trên bị coi là bản trùng.

Mở rộng biến môi trường trong .mcp.json

Cơ chế này cho team chia sẻ cấu hình mà vẫn linh hoạt với path riêng theo máy và giá trị nhạy cảm như API key.

Cú pháp: ${VAR} nở thành giá trị của biến VAR; ${VAR:-default} nở thành VAR nếu được set, ngược lại dùng default.

Nở được ở năm chỗ: command, args, env, url (cho HTTP), và headers.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Nếu một biến được tham chiếu không được set và không có giá trị mặc định, config vẫn nạp: Claude Code báo cảnh báo thiếu biến cho server đó trong output claude mcp list và dùng nguyên văn text ${VAR} chưa nở. Hãy set biến hoặc thêm fallback :-default.

Một chi tiết dễ vấp: CLAUDE_PROJECT_DIR được set trong môi trường của server, không phải trong môi trường của chính Claude Code — nên tham chiếu nó bằng ${VAR} trong command hoặc args của một entry .mcp.json cần một giá trị mặc định, dạng ${CLAUDE_PROJECT_DIR:-.}. Cấu hình MCP do plugin cung cấp thì thay thế ${CLAUDE_PROJECT_DIR} trực tiếp và không cần mặc định.

Xác thực với remote server

Nhiều MCP server trên cloud yêu cầu xác thực. Claude Code hỗ trợ OAuth 2.0.

Claude Code đánh dấu một remote server là cần xác thực khi server phản hồi 401 Unauthorized hoặc 403 Forbidden.

Luồng thông thường: thêm server, rồi chạy /mcp trong Claude Code và theo các bước đăng nhập trong trình duyệt.

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

Bốn hành vi tự động đáng biết:

  • Khi một request tới server OAuth bạn đã đăng nhập trả về 401, Claude Code tự refresh token, nối lại, và thử lại request một lần. Nó chỉ gắn cờ server trong /mcp nếu lần thử lại đó cũng fail.
  • Khi refresh token fail vì server từ chối refresh token đã lưu, Claude Code hiện ngay một thông báo trỏ tới /mcp. Menu của server đó cung cấp Re-authenticate.
  • Claude Code hiện thông báo lúc khởi động khi có server cần xác thực, nên bạn không phải mở /mcp mới biết.
  • Ở chế độ non-interactive không có panel /mcp, nên Claude Code không chạy được luồng OAuth hộ bạn. Nó nói cho Claude biết tool của server đó không khả dụng tới khi bạn cấp phép — nên Claude nêu tên server cần đăng nhập thay vì trả lời như thể server không được cấu hình. Hoàn tất đăng nhập từ một phiên tương tác bằng /mcp hoặc claude mcp login <name>.

Mẹo thực dụng: token xác thực được lưu an toàn và tự refresh. Dùng Clear authentication trong menu /mcp để thu hồi quyền. Nếu redirect của trình duyệt fail sau khi bạn đã xác thực, dán toàn bộ callback URL từ address bar vào ô nhập URL hiện ra trong Claude Code.

Nếu bạn đã cấu hình headers.Authorization cho server mà server từ chối header đó, Claude Code báo kết nối fail chứ không lùi về luồng OAuth. Kiểm tra token còn hợp lệ với endpoint MCP, hoặc xoá header đi để dùng OAuth.

Tool search: giữ context thấp khi có nhiều server

Đây là phần nối trực tiếp với phần 3. Tool search giữ mức dùng context của MCP ở mức thấp bằng cách hoãn định nghĩa tool tới khi Claude cần. Chỉ tên tool và server instructions nạp lúc đầu phiên, nên thêm nhiều MCP server gần như không ảnh hưởng context window.

Claude Code không áp giới hạn cứng số tool cho mỗi server; giới hạn thực tế là ngân sách context của bạn.

Tool search bật mặc định. MCP tool được hoãn thay vì nạp trước, và Claude dùng một tool tìm kiếm để phát hiện cái liên quan khi task cần. Chỉ tool Claude thực sự dùng mới vào context. Từ góc nhìn của bạn, MCP tool hoạt động y như trước.

Giá trị ENABLE_TOOL_SEARCHHành vi
(không set)Mọi MCP tool được hoãn và nạp theo nhu cầu. Lùi về nạp trước trên vài provider/model cũ, khi ANTHROPIC_BASE_URL là host không phải first-party, hoặc trên deployment Microsoft Foundry host trên Azure
trueMọi MCP tool được hoãn. Claude Code gửi beta header qua proxy, và request fail trên proxy không hỗ trợ tool_reference block
autoChế độ ngưỡng: nạp trước khi tổng định nghĩa dưới 10% context window, và hoãn tất cả khi chúng đạt 10%
auto:NChế độ ngưỡng với phần trăm tuỳ chỉnh, N từ 0 tới 100. Ví dụ auto:5 cho 5%
falseMọi MCP tool nạp trước, không hoãn gì

Tool search cần model hỗ trợ tool_reference block: Claude Sonnet 4.5, Haiku 4.5, Opus 4.5 trở lên.

Nếu bạn đang viết một MCP server, trường server instructions trở nên hữu ích hơn khi tool search bật — nó giúp Claude hiểu khi nào nên tìm tool của bạn, tương tự cách skill hoạt động. Hãy ghi rõ: nhóm task nào tool của bạn xử lý, khi nào Claude nên tìm tới chúng, và các năng lực chính. Claude Code cắt mô tả tool và server instructions ở 2KB mỗi cái — giữ chúng ngắn, và đặt chi tiết quan trọng lên đầu.

Chạy /mcp để xem trạng thái kết nối và chi phí token theo từng server.

Tham chiếu MCP resource bằng @

MCP server phơi ra được resource mà bạn tham chiếu bằng @ mention, tương tự cách tham chiếu file.

Gõ @ trong prompt để xem resource khả dụng từ mọi server đã nối — chúng hiện cạnh file trong menu autocomplete. Cú pháp là @server:protocol://resource/path:

Can you analyze @github:issue://123 and suggest a fix?
Please review the API documentation at @docs:file://api/authentication
Compare @postgres:schema://users with @docs:file://database/user-model

Bốn điều đáng biết: resource được tự động tải và đính kèm khi được tham chiếu; đường dẫn resource tìm kiếm mờ được trong autocomplete; Claude Code tự cấp tool để liệt kê và đọc MCP resource khi server hỗ trợ; và resource chứa được bất kỳ loại nội dung nào server cung cấp — text, JSON, dữ liệu có cấu trúc.

Tự dựng một MCP server

Muốn để Claude dựng khung server hộ bạn thì dùng plugin chính thức mcp-server-dev:

/plugin install mcp-server-dev@claude-plugins-official

Nếu cài fail, khớp theo thông báo: Marketplace "claude-plugins-official" not found → thêm marketplace bằng /plugin marketplace add anthropics/claude-plugins-official rồi thử lại. Nếu bản tóm tắt cài đặt báo Run /reload-plugins to activate., chạy lệnh đó.

Rồi chạy skill dựng khung:

/mcp-server-dev:build-mcp-server

Claude hỏi về use case của bạn và dựng khung một remote HTTP server hoặc một local stdio server.

Điều gì tiếp theo

Bạn đã có bốn cơ chế mở rộng: skill (phần 12), hook (phần 13), MCP (bài này), và CLAUDE.md (phần 4). Phần 15 nói về tầng đóng gói — plugin và marketplace, thứ gộp cả bốn lại thành một đơn vị cài đặt được.

Nguồn

Docs gốc cập nhật thường xuyên; khi có mâu thuẫn, tin bản tiếng Anh.