Cấu hình MCP trong the VS Code Extension

Nếu bạn đã quen dùng Claude Code (CLI) và giờ chuyển qua làm việc trong VS Code, việc cấu hình MCP (Model Context Protocol) trong extension có vài điểm khác biệt đáng chú ý so với terminal — từ nơi lưu config, cách UI hiển thị server, đến cách bạn xác minh tool đã sẵn sàng cho agent dùng. Bài này đi từ A đến Z: cài extension, mở đúng panel cấu hình, thêm server local (stdio) và remote (SSE/HTTP), rồi verify toàn bộ pipeline bằng prompt thực tế. Đây là quy trình mình dùng hàng ngày khi setup MCP cho các dự án enterprise, nơi một nửa server là internal tool chạy qua stdio, nửa còn lại là SaaS API expose qua HTTP.

Cài đặt Claude Code VS Code Extension

Trước khi đụng tới MCP, bạn cần có extension chạy đúng cách trong VS Code (hoặc các fork tương thích như Cursor, Windsurf — tuy UI có thể lệch đôi chỗ).

Cài qua Marketplace

Cách nhanh nhất:

1. Mở VS Code, vào tab Extensions (Cmd+Shift+X trên macOS, Ctrl+Shift+X trên Windows/Linux).
2. Tìm "Claude Code".
3. Chọn extension chính thức của Anthropic, bấm Install.
4. Reload VS Code khi được yêu cầu.

Hoặc cài bằng command line nếu bạn thích scripting việc setup máy mới:

code --install-extension anthropic.claude-code

Cài qua CLI có sẵn

Nếu máy bạn đã cài Claude Code CLI (npm install -g @anthropic-ai/claude-code), mở integrated terminal trong VS Code và gõ:

claude

Claude Code sẽ tự phát hiện đang chạy trong VS Code và gợi ý cài extension đồng bộ (companion extension) để có sidebar, inline diff, và context sharing giữa terminal session và editor. Đồng ý cài là cách đơn giản nhất, vì nó đảm bảo version CLI và extension khớp nhau — tránh tình trạng lệch version gây lỗi lặt vặt khi parse MCP config.

Xác nhận cài đặt thành công

Sau khi cài, kiểm tra:

• Icon Claude Code xuất hiện ở Activity Bar (thanh biểu tượng bên trái).
• Command Palette (Cmd+Shift+P) có các lệnh bắt đầu bằng "Claude Code:".
• Status bar dưới cùng hiển thị trạng thái kết nối (đã login hay chưa).

Mẹo: Nếu bạn dùng nhiều workspace VS Code khác nhau (ví dụ: một cho monorepo backend, một cho mobile app), cài extension ở cấp User (không phải Workspace-only) để tránh phải cài lại mỗi lần mở project mới. Vào Extensions panel, click phải vào Claude Code, chọn "Install (do not sync)" chỉ khi bạn cố tình muốn cấu hình khác nhau theo máy.

Mở và chỉnh sửa MCP Settings Panel trong VS Code

Đây là phần nhiều người mới dùng hay lẫn lộn: MCP config trong VS Code extension có thể tồn tại ở ba cấp độ — user-level (global), workspace-level (project), và local override (không commit vào git). Hiểu rõ ba lớp này giúp bạn tránh tình trạng "tôi thêm server rồi mà sao agent không thấy".

Cách mở panel cấu hình

Có hai đường vào:

1. Qua UI: Click icon Claude Code ở Activity Bar → chọn tab "MCP Servers" (hoặc biểu tượng plug/ổ cắm) → bạn sẽ thấy danh sách server hiện có kèm trạng thái (connected/disconnected/error).
2. Qua Command Palette: Cmd+Shift+P → gõ "Claude Code: Open MCP Settings" → VS Code mở file JSON tương ứng để bạn chỉnh trực tiếp.

Cách thứ hai là cách mình khuyên dùng khi bạn cần thêm nhiều server một lúc hoặc copy config từ máy khác, vì UI form-based thường chỉ hỗ trợ thêm/sửa một server tại một thời điểm.

Vị trí file config thực tế

Tùy cấp độ, file JSON nằm ở:

• User/global: thường là ~/.claude.json hoặc thư mục config của Claude Code (~/.config/claude-code/mcp.json tùy version) — áp dụng cho mọi project bạn mở.
• Workspace: .vscode/mcp.json hoặc .mcp.json ở root project — nên commit vào git để cả team dùng chung server (trừ secret).
• Local override: .claude/settings.local.json hoặc biến tương đương — dùng cho API key cá nhân, không commit.

Cấu trúc JSON cơ bản của một MCP config file trong VS Code extension:

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-example"],
      "env": {
        "API_KEY": "${env:EXAMPLE_API_KEY}"
      }
    }
  }
}

Lưu ý cú pháp ${env:VAR_NAME} — extension hỗ trợ interpolation biến môi trường ngay trong JSON, nghĩa là bạn không cần hardcode secret vào file commit lên git.

Reload sau khi sửa

Sau khi save file JSON, extension không luôn tự động reload. Cách chắc ăn nhất:

• Mở Command Palette → "Claude Code: Reload MCP Servers", hoặc
• Đóng và mở lại panel MCP Servers, hoặc
• Trong trường hợp cứng đầu, reload toàn bộ VS Code window (Cmd+Shift+P → "Reload Window").

Mẹo: Đặt file workspace config (.mcp.json) ở root repo và commit nó — nhưng tách phần secret (API key, token) ra file .env hoặc settings.local.json được gitignore. Cách này giúp onboard dev mới chỉ cần cp .env.example .env rồi điền key, không phải hỏi nhau "server nào cần cấu hình gì".

Thêm MCP Server Local và Remote trong Extension

Đây là phần kỹ thuật quan trọng nhất: MCP hỗ trợ hai kiểu transport chính, và cách khai báo trong VS Code extension khác nhau rõ rệt giữa hai loại.

Local server (stdio transport)

Server local chạy như một subprocess trên máy bạn, giao tiếp qua stdin/stdout (transport stdio). Đây là kiểu phổ biến nhất cho tool nội bộ — filesystem access, database query, chạy script custom.

Ví dụ config server đọc file trong một thư mục cụ thể (dùng package chính thức @modelcontextprotocol/server-filesystem):

{
  "mcpServers": {
    "filesystem-local": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Projects/my-repo"
      ]
    }
  }
}

Ví dụ server custom tự viết bằng Python, chạy qua stdio:

{
  "mcpServers": {
    "internal-jira-tool": {
      "command": "python",
      "args": ["-m", "mcp_servers.jira_stdio"],
      "cwd": "/Users/you/Projects/internal-mcp-tools",
      "env": {
        "JIRA_TOKEN": "${env:JIRA_API_TOKEN}",
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net"
      }
    }
  }
}

Điểm cần nhớ với stdio server:

• command phải là executable có sẵn trong PATH của process VS Code (đôi khi khác PATH của terminal bạn dùng — đây là lỗi rất hay gặp trên macOS khi dùng nvm hoặc pyenv).
• cwd (working directory) nên khai báo rõ nếu server cần load file config tương đối.
• Log lỗi của stdio server thường xuất hiện trong Output panel của VS Code, chọn channel "Claude Code" hoặc "MCP".

Remote server (SSE / Streamable HTTP transport)

Server remote chạy trên hạ tầng khác (server nội bộ công ty, hoặc SaaS bên thứ ba expose MCP endpoint), giao tiếp qua HTTP — dùng SSE (Server-Sent Events) hoặc Streamable HTTP tùy version protocol.

Ví dụ config remote server dùng Streamable HTTP với Bearer token auth:

{
  "mcpServers": {
    "internal-analytics-api": {
      "url": "https://mcp.yourcompany.internal/analytics",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${env:ANALYTICS_MCP_TOKEN}"
      }
    }
  }
}

Ví dụ config remote server dùng SSE (một số server MCP đời cũ hơn vẫn chỉ hỗ trợ transport này):

{
  "mcpServers": {
    "docs-search-remote": {
      "url": "https://mcp.example-vendor.com/sse",
      "transport": "sse",
      "headers": {
        "X-API-Key": "${env:VENDOR_MCP_API_KEY}"
      }
    }
  }
}

Nếu server remote yêu cầu OAuth flow (thay vì static token), extension VS Code thường hiển thị notification yêu cầu bạn đăng nhập qua browser lần đầu — sau đó lưu token vào secure storage của VS Code, không phải trong file JSON plain text.

Bảng so sánh nhanh local vs remote

Mẹo: Khi mới thêm remote server, luôn test bằng curl trước khi nhúng vào config JSON — kiểm tra endpoint trả đúng response MCP handshake (initialize request) chứ không phải lỗi 401/404 âm thầm. Việc này tiết kiệm rất nhiều thời gian debug so với việc đoán mò trong VS Code UI.

Xác minh MCP Tools đã sẵn sàng trong Workspace

Thêm server vào config chưa chắc đồng nghĩa agent đã "nhìn thấy" tool. Bước verify này là bước hay bị bỏ qua nhất — và cũng là bước cứu bạn nhiều giờ debug sau này.

Bước 1: Kiểm tra trạng thái kết nối server

Trong panel "MCP Servers" của extension, mỗi server sẽ có một trong các trạng thái:

• Connected (thường màu xanh): handshake thành công, tool list đã load.
• Error: sai command, sai path, hoặc auth thất bại — click vào server để xem chi tiết log.
• Disconnected/Disabled: server bị tắt thủ công hoặc chưa được reload.

Nếu thấy Error, mở Output panel (Cmd+Shift+P → "View: Toggle Output") → chọn dropdown bên phải → "Claude Code" hoặc "MCP Server: " để đọc stack trace đầy đủ.

Bước 2: Liệt kê tool đã expose

Dùng Command Palette: "Claude Code: List MCP Tools" (tên lệnh có thể khác tùy version), hoặc đơn giản hơn — mở chat panel của Claude Code và hỏi thẳng:

Bạn đang có những MCP tool nào khả dụng trong workspace này? Liệt kê tên tool và server nguồn của từng tool.

Agent sẽ trả về danh sách tool kèm tên server, ví dụ: filesystem-local::read_file, internal-jira-tool::search_issues. Nếu tool bạn vừa thêm không xuất hiện, quay lại kiểm tra bước reload ở phần trước.

Bước 3: Test tool bằng prompt thực tế

Đừng chỉ tin vào danh sách — thử gọi thật. Ví dụ với server filesystem local:

Dùng tool filesystem-local để đọc file package.json ở root project và cho tôi biết version hiện tại của dependency "react".

Với server remote analytics:

Gọi tool từ internal-analytics-api để lấy số lượng active user trong 7 ngày qua, rồi tóm tắt xu hướng tăng/giảm.

Nếu agent trả lời được đúng dữ liệu thật (không phải bịa/hallucinate), nghĩa là pipeline từ config JSON → transport → tool call → response đã hoạt động trơn tru.

Bước 4: Kiểm tra permission và approval flow

Claude Code có cơ chế approval cho tool call (đặc biệt với tool có khả năng ghi/xóa dữ liệu). Trong VS Code, approval này hiện dưới dạng popup hoặc inline confirmation trong chat panel. Verify rằng:

• Tool read-only (như read_file, search_issues) không bị chặn approval liên tục gây khó chịu (bạn có thể whitelist trong settings).
• Tool có tác động (write, delete, deploy) luôn yêu cầu xác nhận rõ ràng — đừng tắt approval cho nhóm này chỉ vì muốn "nhanh hơn".

Mẹo: Tạo một topic/prompt "health check" cố định, kiểu như đoạn trên, và lưu nó làm snippet hoặc slash command riêng. Mỗi khi thêm server mới hoặc sau khi update extension, chạy lại health check này để phát hiện sớm server nào bị đứt kết nối — thay vì đợi tới lúc đang làm task thật mới phát hiện ra.

Mẹo

Tổng hợp những kinh nghiệm thực chiến khi làm việc với MCP trong Claude Code VS Code extension:

Mẹo: Phân biệt rõ config workspace (.mcp.json commit git) và config local (secret, không commit) ngay từ đầu project. Nhiều team gặp sự cố lộ API key vì lỡ tay commit file chứa token thẳng vào JSON — luôn dùng ${env:...} interpolation.

Mẹo: Khi debug server stdio không connect được, thử chạy chính command đó (command + args) trực tiếp trong terminal VS Code trước — nếu nó chạy được ở terminal nhưng extension báo lỗi, khả năng cao là vấn đề PATH hoặc biến môi trường không được extension kế thừa đúng.

Mẹo: Với server remote dùng OAuth, restart VS Code sau lần đăng nhập đầu tiên nếu thấy tool list không load — đôi khi token cần một vòng reload để propagate vào MCP client session.

Mẹo: Đừng thêm quá nhiều server cùng lúc vào một workspace nếu chưa cần — mỗi server thêm vào đều tăng số lượng tool definition nạp vào context window (cửa sổ ngữ cảnh) của model, có thể làm giảm chất lượng lựa chọn tool khi số lượng tool quá lớn và chồng chéo chức năng. Chỉ enable server thật sự cần cho task đang làm.

Mẹo: Version của extension và version CLI nên đồng bộ — nếu bạn update CLI qua npm update -g @anthropic-ai/claude-code nhưng quên update extension (hoặc ngược lại), một số MCP feature mới (như transport HTTP thế hệ mới) có thể không được hỗ trợ đồng nhất, dẫn đến lỗi khó hiểu dù config đúng cú pháp.