Sử dụng MCP connector đúng cách

Tại sao bài học này quan trọng hơn vẻ bề ngoài của nó?

Các connector là phần ít được đề cập nhất trong Routines. Tài liệu hướng dẫn ban đầu chỉ dành vài đoạn cho chúng. Mọi hướng dẫn đều bỏ qua bước "cài đặt Notion MCP". Trong khi đó, cấu hình sai connector chiếm phần lớn các lỗi trong tuần đầu tiên: Những routine không tìm thấy dữ liệu, các routine có quá nhiều quyền truy cập, những routine tự động ngừng hoạt động khi OAuth token hết hạn.

Trong bài học này, bạn sẽ học mô hình chuẩn hoạt động cho mọi MCP connector được hỗ trợ bởi OAuth. Khi bạn hiểu luồng hoạt động của một connector (chúng ta sẽ sử dụng Notion), bạn sẽ hiểu nó cho tất cả các connector khác.

MCP connector thực sự là gì?

Model Context Protocol (MCP) là cách Claude Code giao tiếp với các dịch vụ bên ngoài. connector là một "máy chủ" MCP - một quy trình nhỏ hoặc endpoint được host đóng vai trò trung gian giữa Claude và dịch vụ ở phía bên kia.

Khi bạn thấy "Notion MCP" trong danh sách các connector, điều thực sự đang xảy ra là:

• Có một máy chủ Notion MCP ở đâu đó (được host hoặc cục bộ)
• Claude Code gửi các thông báo định dạng MCP đến máy chủ đó
• Máy chủ xác thực với Notion thay mặt bạn
• Máy chủ hiển thị các thao tác của Notion cho Claude dưới dạng "công cụ" (tìm kiếm trang, đọc database, tạo trang, v.v...)

Đối với các routine, đám mây của Anthropic gọi connector thay mặt cho routine của bạn, sau đó hiển thị những công cụ đó bên trong phiên Claude Code của routine.

OAuth flow chuẩn (Ví dụ Notion)

Thiết lập Notion MCP là một trong những thiết lập rõ ràng nhất và tương ứng trực tiếp với Gmail, Slack, Linear và hầu hết các connector được hỗ trợ bởi OAuth khác. Đây là quy trình, từng bước một:

Bước 1: Tạo gói công cụ

Trong bảng điều khiển của nhà cung cấp MCP (đối với MCP được host), hãy tạo một gói công cụ. Đây là một gói các thao tác được đặt tên mà bạn sẵn sàng hiển thị cho Claude.

Đối với Notion, một bộ công cụ khởi đầu có thể bao gồm:

• search_pages - tìm kiếm toàn văn trên toàn bộ không gian làm việc của bạn
• read_page - lấy nội dung của một trang
• read_database - truy vấn database Notion
• create_page - tạo một trang mới (tùy chọn - hãy cân nhắc kỹ)

Cố ý loại trừ các thao tác bạn không cần: delete_page, update_permissions, create_database. Bộ công cụ là cổng giới hạn phạm vi đầu tiên của bạn.

Bước 2: Thêm người dùng đã đăng ký

Người dùng đã đăng ký đại diện cho Claude Code như một danh tính. Hãy coi nó như một tài khoản dịch vụ.

Khi tạo nó, bạn sẽ nhận được một URL MCP duy nhất - đây là cách Claude Code tìm thấy connector. Hãy giữ URL này riêng tư; về cơ bản nó là một thông tin xác thực.

Bước 3: Xác thực dịch vụ mục tiêu

Từ trang người dùng đã đăng ký, hãy bắt đầu OAuth flow cho Notion. Điều này sẽ mở màn hình xác thực của Notion.

Bước quan trọng: Khi Notion hỏi bạn muốn chia sẻ những trang và database nào, hãy giới hạn phạm vi thật chặt chẽ. Đừng nhấp vào "chia sẻ toàn bộ không gian làm việc" trừ khi routine thực sự cần thiết. Chỉ chia sẻ:

• Database cụ thể mà routine đọc từ đó
• Trang hoặc thư mục cụ thể mà routine ghi vào

Nếu Notion cho phép bạn chọn "Sub-pages included: no", hãy chọn tùy chọn đó. Nếu bạn đang chia sẻ database, chỉ chia sẻ database đó, không phải database cha của nó.

Đây là quyết định bảo mật quan trọng nhất bạn sẽ đưa ra với các MCP connector. Một routine bị xâm phạm có thể làm chính xác những gì phạm vi OAuth của nó cho phép - không hơn không kém.

Bước 4: Thu thập thông tin xác thực

Bây giờ bạn có hai thứ:

• MCP URL - nơi Claude Code gửi yêu cầu
• API key - cách Claude Code xác thực với máy chủ MCP

Lưu trữ cả hai trong trình quản lý secret hoặc 1Password của bạn. Bạn sẽ dán chúng vào Claude Code một lần.

Bước 5: Thêm connector vào Claude Code

Trong Claude Code cục bộ của bạn, hãy chạy:

claude mcp add notion \
  --url "https://your-mcp-url.example.com" \
  --key "$NOTION_MCP_KEY"

Kiểm tra xem nó có hoạt động không:

claude mcp list

Bạn sẽ thấy notion trong danh sách với trạng thái connected.

Bước 6: Kích hoạt cho Routines

Mở Claude web hoặc desktop → Settings → Connectors. Notion connector của bạn hiện đã được liệt kê. Nó có sẵn cho bất kỳ routine nào sử dụng.

Khi bạn tạo một routine mới, Notion connector sẽ xuất hiện trong biểu mẫu routine. Hãy nhớ từ bài học 2: nó được bật theo mặc định. Hãy tắt nó trừ khi routine thực sự cần đến nó.

Cùng một flow, nhưng với các connector khác nhau

Các bước chính xác có thể khác nhau một chút tùy thuộc vào dịch vụ, nhưng mẫu chung là giống nhau. Đây là cách nó được ánh xạ:

Nguyên tắc: Tạo một nhóm các thao tác, xác thực Claude với dịch vụ với phạm vi quyền hạn hẹp nhất có thể, thu thập thông tin đăng nhập, thêm vào Claude Codde, đính kèm cho mỗi routine.

Postgres: Trường hợp database

Postgres hơi khác một chút vì mô hình xác thực là tên người dùng + mật khẩu, không phải OAuth. Nguyên tắc vẫn áp dụng - quyền hạn tối thiểu - nhưng cách triển khai là:

1. Tạo một người dùng database chuyên dụng có tên rõ ràng như claude_routines_readonly
2. Cấp quyền SELECT chỉ trên các bảng cụ thể mà routine cần: sql GRANT SELECT ON orders, customers, subscriptions TO claude_routines_readonly;
3. Không bao giờ cấp quyền INSERT, UPDATE, DELETE hoặc ALL PRIVILEGES
4. Sử dụng SSL - không kết nối qua TCP thông thường
5. Thêm vào Claude Code với chuỗi kết nối trong trình quản lý secret của bạn

Một routine chỉ có thể đọc các bảng cụ thể an toàn hơn nhiều so với một routine có quyền truy cập đầy đủ vào database. Nó cũng dễ gỡ lỗi hơn ("tại sao hàng này lại bị sửa đổi?") vì bạn biết rằng routine không phải là nguyên nhân.

3 cạm bẫy thường gặp

Từ những ngày đầu nhận phản hồi từ cộng đồng, 3 kiểu lỗi thường gặp nhất là:

Cạm bẫy 1: Phạm vi OAuth quá rộng khi thiết lập

Ai đó nhấp vào "Share entire workspace" trong Notion, "Full mailbox" trong Gmail, "All channels" trong Slack. Routine hoạt động - nhưng nó nguy hiểm hơn gấp 10 lần so với mức cần thiết. Nếu prompt có lỗi (hoặc API key bị rò rỉ), phạm vi ảnh hưởng sẽ là toàn bộ không gian làm việc.

Cách khắc phục: Tại thời điểm OAuth, hãy giới hạn phạm vi cho tài nguyên cụ thể. Nếu bạn không thể giới hạn phạm vi hẹp hơn, hãy sử dụng một tài khoản riêng biệt chỉ có quyền truy cập vào những gì routine cần.

Cạm bẫy 2: Token hết hạn sau khoảng 30 ngày

OAuth token hết hạn. Nếu routine của bạn hoạt động tốt trong hai tuần và sau đó âm thầm ngừng tạo ra đầu ra, có thể token đã hết hạn. Routine vẫn đang chạy, nhưng connector đang âm thầm bị lỗi.

Cách khắc phục: Kiểm tra lịch sử chạy để tìm lỗi connector. Xác thực lại khi cần. Đối với các routine có độ tin cậy cao, hãy đặt lời nhắc trên lịch để xoay vòng thông tin xác thực hàng tháng. Anthropic đang phát triển tính năng tự động refresh, nhưng đừng quá kỳ vọng vào điều đó ngay bây giờ.

Cạm bẫy 3: Danh sách connector quá tải trong các routine mới

Bạn thiết lập 7 connector trong vòng một tháng. Bạn tạo một routine mới. Cả 7 đều được bật theo mặc định. Routine chỉ cần một connector. Giờ đây, Claude có diện tích bề mặt công cụ gấp 7 lần, ngữ cảnh mỗi lần chạy dài hơn và 7 vị trí có thể xảy ra lỗi.

Cách khắc phục: Hãy đặt thao tác "vô hiệu hóa các connector không sử dụng" là bước thứ hai bạn thực hiện khi tạo một routine mới, ngay sau khi thiết lập trigger.

Bài tập: Kết nối một connector từ đầu đến cuối

Chọn một dịch vụ bạn sử dụng hàng ngày - Notion, Linear, Slack, Gmail hoặc một database Postgres nhỏ. Thực hiện theo 6 bước trên. Cụ thể:

1. Tạo gói công cụ hoặc tập hợp quyền hạn hẹp
2. Tạo thông tin xác thực
3. Chạy lệnh claude mcp add với phạm vi tối thiểu
4. Xác minh bằng lệnh claude mcp list
5. Mở một routine mới → xác nhận connector xuất hiện trong biểu mẫu
6. Sau đó vô hiệu hóa nó (chúng ta sẽ chưa sử dụng nó - chỉ để chứng minh flow hoạt động)

Cuối cùng, bạn sẽ có một connector hoạt động, có phạm vi giới hạn, sẵn sàng để đưa vào các routine cuối khóa của bạn trong bài học 8.

Những điểm chính cần ghi nhớ

• Quy trình chuẩn: Gói công cụ → người dùng đã đăng ký → OAuth có phạm vi → thông tin xác thực → claude mcp add → kích hoạt cho từng routine
• Luôn đặt phạm vi tại thời điểm OAuth, không phải sau đó - phạm vi hẹp tốt hơn phạm vi rộng
• Postgres tuân theo nguyên tắc tương tự với người dùng DB: Chỉ đọc, chuyên dụng, bảng cụ thể
• Ba cạm bẫy: Phạm vi rộng, hết hạn token, danh sách connector quá tải trong các routine mới
• Vô hiệu hóa các connector không sử dụng khi tạo mỗi routine mới