Tích hợp MCP server vào Claude Code và agent

MCP server là cách cho Claude Code hay agent của bạn dùng được các hệ thống bên ngoài: GitHub, Jira, cơ sở dữ liệu, hay một hệ thống nội bộ. Cài một server thì dễ. Khó hơn là đặt cấu hình ở đâu cho đúng người dùng, giữ bí mật token, và làm sao để agent thật sự dùng tool đó.

Bài này giúp bạn trả lời: cấu hình MCP server ở chỗ nào, và làm gì để agent dùng nó hiệu quả?

Ví dụ xuyên suốt: nhóm phát triển app gọi xe

Nhóm 8 người phát triển một app gọi xe công nghệ, dùng Claude Code hằng ngày. Họ muốn Claude Code dùng được:

1. GitHub: đọc issue, pull request.
2. Jira: đọc và cập nhật ticket.
3. Hệ thống chỉ mục code nội bộ: tìm hàm theo ý nghĩa, biết hàm nào gọi hàm nào, do nhóm tự viết.
4. Riêng Khoa muốn thử một MCP server mới để vẽ sơ đồ, chưa chắc cả nhóm cần.

MCP server cấp project và cấp user

GitHub, Jira và hệ thống chỉ mục code là công cụ cả nhóm dùng, nên đặt ở .mcp.json rồi commit. Ai clone repo về cũng có đủ.

Server vẽ sơ đồ của Khoa chỉ đang thử, đặt ở cấp user trong ~/.claude.json. Không ai khác bị ảnh hưởng.

Tài liệu Claude Code ghi thêm: với server cấp project lấy từ .mcp.json, Claude Code sẽ hỏi bạn có đồng ý dùng không trước khi chạy, để tránh một file cấu hình lạ tự kéo server vào máy.

Giữ token bằng biến môi trường

Server GitHub cần token. Viết thẳng token vào .mcp.json rồi commit là lộ token cho bất kỳ ai đọc được repo.

Claude Code cho phép dùng biến môi trường trong .mcp.json với cú pháp ${TEN_BIEN}, hoặc ${TEN_BIEN:-gia_tri_mac_dinh}. Mỗi người tự đặt biến trên máy mình, file commit lên chỉ có tên biến:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://github-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    },
    "code-index": {
      "command": "node",
      "args": ["tools/code-index-server.js"],
      "env": { "INDEX_URL": "${CODE_INDEX_URL:-http://localhost:4100}" }
    }
  }
}

Theo tài liệu, biến môi trường dùng được trong các trường command, args, env, url và headers.

Mọi tool MCP đều sẵn sàng cùng lúc

Khi Claude Code kết nối với các MCP server, nó nhận biết tool của tất cả server đã cấu hình, và agent dùng được tool của mọi server cùng lúc. Không có bước chọn server trước, cũng không phải mỗi lượt chỉ dùng được một server. Trong ví dụ, Claude có thể đọc một issue GitHub, tìm hàm liên quan bằng hệ thống chỉ mục code, rồi cập nhật ticket Jira trong cùng một yêu cầu.

Để tiết kiệm context, Claude Code bản hiện tại còn bật sẵn tool search: lúc mở phiên chỉ nạp tên các tool MCP, còn phần mô tả đầy đủ của tool nào thì khi Claude cần mới nạp. Tool vẫn dùng được đủ, chỉ là nạp dần.

Tool MCP có tên dạng mcp__<tên server>__<tên tool>, ví dụ mcp__code-index__find_callers.

Viết mô tả để agent chịu dùng tool MCP

Nhóm để ý: hỏi "hàm tính cước giờ cao điểm được gọi ở đâu?", Claude Code thường dùng Grep có sẵn để tìm chữ, thay vì dùng find_callers của hệ thống chỉ mục, dù find_callers cho kết quả chính xác hơn nhiều.

Lý do: tool MCP có mô tả quá ngắn, "Tìm nơi gọi hàm". Claude không thấy nó hơn Grep ở điểm nào. Cách sửa giống bài 2.1: viết mô tả nói rõ khả năng và đầu ra.

find_callers: Tìm mọi nơi gọi một hàm, kể cả gọi gián tiếp qua re-export,
alias hay dependency injection, những chỗ mà tìm chữ bằng Grep sẽ bỏ sót.
Trả về danh sách file, dòng, và chuỗi gọi từ điểm vào tới hàm đó.
Dùng thay cho Grep khi cần biết ai gọi một hàm.

Dùng server có sẵn hay tự viết

GitHub và Jira là tích hợp phổ biến, đã có MCP server do cộng đồng hoặc chính nhà cung cấp làm. Nhóm nên dùng luôn, không tự viết lại.

Hệ thống chỉ mục code là của riêng nhóm, không ai làm sẵn. Đây mới là chỗ đáng tự viết một MCP server.

MCP resources: cho agent biết có dữ liệu gì

Ngoài tool, MCP server còn có thể cung cấp resources: các mục nội dung có địa chỉ riêng, ví dụ danh sách issue đang mở, cấu trúc tài liệu, sơ đồ bảng cơ sở dữ liệu. Theo đặc tả MCP, resources dùng để chia sẻ dữ liệu làm ngữ cảnh cho model, như file, schema cơ sở dữ liệu hay thông tin riêng của ứng dụng.

Lợi ích: thay vì agent phải gọi tool nhiều lần để dò "có bảng nào, mỗi bảng có cột gì", server đưa luôn một mục lục. Agent nhìn mục lục là biết có gì, đỡ hẳn những lần gọi tool chỉ để thăm dò.

Trong Claude Code, bạn nhắc tới một resource bằng @, theo dạng @server:protocol://đường/dẫn, ví dụ @github:issue://123.