Hướng dẫn kết nối Activepieces với MCP từng bước một

Việc kết nối Activepieces với MCP cho phép bạn sử dụng trợ lý trí tuệ nhân tạo để Tạo, xem xét và kiểm thử các quy trình tự động hóa sử dụng ngôn ngữ tự nhiên.Thay vì tự tay xây dựng từng bước từ trình chỉnh sửa trực quan, bạn có thể yêu cầu trình hướng dẫn kiểm tra các tích hợp có sẵn, thiết lập bản nháp và phát hiện lỗi trước khi xuất bản.

Activepieces tích hợp máy chủ riêng tương thích với... Giao thức ngữ cảnh mô hìnhMáy chủ này đóng vai trò là giao diện tiêu chuẩn giữa nền tảng tự động hóa và các ứng dụng khách như Claude Desktop, Claude.ai, Cursor hoặc Windsurf.

Khả năng tích hợp hiện tại vượt xa việc chỉ đơn thuần hiển thị một vài thao tác. Trình hướng dẫn có thể truy vấn cấu trúc luồng, tìm kiếm các thao tác và trình kích hoạt, quản lý bảng, phân tích các lần thực thi thất bại và, nếu bạn cấp cho nó các quyền thích hợp, chỉnh sửa hoặc xuất bản các quy trình tự động hóa hoàn chỉnh.

Máy chủ Activepieces MCP cho phép bạn làm những gì?

Máy chủ Activepieces MCP cho phép một trình hướng dẫn tương thích hoạt động trên một dự án trong nền tảng. Chức năng chính của nó không phải là thay thế công cụ tự động hóa, mà là cung cấp cho mô hình một bộ công cụ được kiểm soát để thực hiện các thao tác. kiểm tra và quản lý các luồng thông qua cuộc trò chuyện.

Ví dụ, bạn có thể yêu cầu nó thực hiện những điều sau:

• Liệt kê các luồng hiện có và kiểm tra xem luồng nào đang được kích hoạt.
• Hãy tìm hiểu cấu trúc và cấu hình của một hệ thống tự động hóa.
• Hãy tìm hành động thích hợp cho nhiệm vụ được giao.
• Tạo một quy trình hoàn chỉnh bao gồm cả yếu tố kích hoạt và hành động.
• Thêm điều kiện, vòng lặp hoặc nhánh vào luồng hiện có.
• Kiểm tra lại cấu hình trước khi công bố.
• Hãy thử từng bước một và xem xét kết quả.
• Xem xét các lần thực thi không thành công và giải thích lỗi gặp phải.
• Tạo và chỉnh sửa bảng hoặc bản ghi Activepieces.

Bạn cũng có thể tìm hiểu về cổ phần thuộc về các công ty khác nhau. Mảnh của nền tảng. Một "Mảnh" (Piece) là sự tích hợp kết nối các yếu tố kích hoạt và hành động có sẵn cho một dịch vụ, chẳng hạn như Gmail, Slack, Google Sheets hoặc HubSpot.

Điều này không nên bị nhầm lẫn với các đại lý bản địa của ActivepiecesMột tác nhân được tạo ra trong nền tảng là một phần của quy trình tự động hóa và sử dụng mô hình để đưa ra quyết định trong quá trình thực thi. Mặt khác, máy chủ MCP cho phép một trợ lý bên ngoài xây dựng, kiểm tra hoặc quản lý dự án.

Những thứ bạn cần để kết nối Activepieces với MCP

Trước khi bắt đầu, hãy đảm bảo bạn đã chuẩn bị đầy đủ những vật dụng sau:

• Tài khoản Activepieces Cloud hoặc bản cài đặt tự quản lý đã được cập nhật.
• Một dự án mà bạn có đủ quyền hạn.
• Một ứng dụng khách tương thích với các máy chủ MCP từ xa.
• Địa chỉ IP công cộng có HTTPS nếu Activepieces được lưu trữ trên máy chủ của bạn.
• Các kết nối cần thiết đã được cấu hình trong dự án.

Bạn không cần cài đặt Node.js hoặc chạy máy chủ MCP riêng biệt. Activepieces đã bao gồm điểm cuối cần thiết và cung cấp địa chỉ tương tự như sau:

https://tu-instancia.example.com/mcp

Nếu bạn sử dụng các ứng dụng như Slack, Google Drive hoặc CRM, trước tiên hãy cấu hình kết nối của chúng từ giao diện Activepieces. Trình hướng dẫn sẽ có thể chọn một kết nối hiện có, nhưng Bạn sẽ không nhận được mật khẩu, khóa API hoặc mã thông báo OAuth..

Hướng dẫn cách kích hoạt máy chủ Activepieces MCP

Máy chủ được kích hoạt từ cài đặt dự án:

1. Đăng nhập vào Activepieces.
2. Mở dự án mà bạn muốn kết nối.
3. Đi vào Cài đặt.
4. Lựa chọn Máy chủ MCP.
5. Kích hoạt máy chủ bằng công tắc tương ứng.
6. Xem lại các loại công cụ được phép sử dụng.
7. Sao chép địa chỉ được hiển thị trong URL máy chủ.

Quyền truy cập được áp dụng cho từng dự án. Điều này cho phép trợ lý kết nối với môi trường thử nghiệm mà không cần cấp cho họ quyền truy cập vào các quy trình làm việc được sử dụng trong môi trường sản xuất.

Đối với lần kết nối đầu tiên, nên chỉ để lại các công cụ truy vấn được kích hoạt. Bạn có thể kích hoạt việc tạo, kiểm thử hoặc xuất bản sau khi đã xác minh cách thức hoạt động của máy khách.

Cách kết nối Claude Desktop, Cursor hoặc Windsurf

Khách hàng hỗ trợ máy chủ MCP từ xa có thể trực tiếp sử dụng URL do Activepieces cung cấp. Cấu trúc cấu hình chung như sau:

{
  "mcpServers": {
    "activepieces": {
      "url": "https://tu-instancia.example.com/mcp"
    }
  }
}

Vị trí của tệp hoặc cài đặt phụ thuộc vào máy khách:

Khách hàng	Vị trí của cấu hình
Con trỏ	.cursor/mcp.json cho dự án hoặc ~/.cursor/mcp.json toàn cầu
Ứng dụng Claude Desktop trên Windows	%APPDATA%\Claude\claude_desktop_config.json
Ứng dụng Claude Desktop trên macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Lướt ván buồm	Cài đặt MCP trong tùy chọn trình chỉnh sửa
Claude.ai	Cài đặt tổ chức > Trình kết nối > Thêm > Trình kết nối tùy chỉnh

Sau khi lưu cài đặt, hãy khởi động lại ứng dụng nếu cần. Trong lần kết nối đầu tiên, một cửa sổ trình duyệt sẽ mở ra để hoàn tất thiết lập. Ủy quyền OAuth với Activepieces.

Đăng nhập, chọn đúng dự án và cấp quyền truy cập được yêu cầu. Hệ thống sẽ lưu trữ mã thông báo ủy quyền; không cần phải sao chép thủ công khóa API vào tệp cấu hình.

Các hướng dẫn cũ hơn có thể hiển thị một lệnh tương tự như sau: npx mcp-remote và một địa chỉ kết thúc bằng /sseCấu hình đó tương ứng với một phiên bản trước đó. Trên các máy khách tương thích hiện tại, bạn phải sử dụng cấu hình sau: URL kết thúc bằng /mcp.

Trợ lý có thể sử dụng những công cụ nào?

Activepieces phân loại các công cụ MCP của mình thành nhiều nhóm. Các công cụ của Khám phá Chúng chỉ có thể đọc và luôn khả dụng. Các danh mục có khả năng chỉnh sửa dữ liệu có thể được bật hoặc tắt trong từng dự án.

Loại	Những điều nó cho phép bạn làm
Khám phá	Xem luồng dữ liệu, kết nối, các thành phần, bảng, quá trình thực thi và lỗi xác thực.
Quản lý dòng chảy	Tạo, sao chép, đổi tên, xuất bản, kích hoạt, vô hiệu hóa hoặc xóa các luồng.
Tòa nhà Flow	Thêm, cập nhật và xóa các trình kích hoạt hoặc hành động.
Bộ định tuyến & Phân nhánh	Tạo và chỉnh sửa các nhánh điều kiện.
Chú thích	Thêm và quản lý ghi chú ngay trong khung vẽ.
Bảng	Tạo bảng, trường và bản ghi, cũng như chỉnh sửa hoặc xóa chúng.
Kiểm thử & Chạy thử	Kiểm thử luồng, thực thi các hành động, xem xét kết quả và thử lại các lần thực thi thất bại.

Một số thao tác có những hậu quả đáng kể. Công cụ xóa quy trình làm việc cũng xóa luôn các phiên bản của nó. Nó không cho phép hoàn tác thao tác.Tương tự, việc thực hiện một hành động có thể gửi email, chỉnh sửa bản ghi hoặc đăng tải nội dung bằng kết nối thực.

Vì lý do này, không nên tự động kích hoạt tất cả các danh mục. Chỉ cấp quyền mà trợ lý cần cho tác vụ hiện tại.

Cách tạo quy trình làm việc Activepieces bằng ngôn ngữ tự nhiên

Sau khi thiết lập kết nối, bạn có thể mô tả quá trình tự động hóa cần thiết. Hướng dẫn càng chính xác, mô hình càng ít phải đưa ra những quyết định mơ hồ.

Ví dụ:

Tạo một bản nháp bị vô hiệu hóa chạy từ thứ Hai đến thứ Sáu lúc 9:00 sáng, truy vấn các bản ghi đang chờ xử lý từ bảng ActivePieces và gửi bản tóm tắt đến Slack. Chỉ sử dụng các kết nối hiện có. Xác thực và kiểm tra luồng, nhưng không công bố nó.

Quy trình thông thường nên tuân theo thứ tự sau:

1. Xem xét dự án: Trình hướng dẫn sẽ kiểm tra các luồng, bảng và kết nối khả dụng.
2. Tìm các công cụ: Xác định yếu tố gây ra sự việc và các hành động phù hợp nhất.
3. Xem xét các đặc tính của nó: Truy xuất các trường bắt buộc và các tùy chọn được cho phép.
4. Soạn thảo bản nháp: Hãy xây dựng trình kích hoạt và các bước theo đúng thứ tự.
5. Xác thực cấu trúc: Kiểm tra các tham chiếu, các nhánh trống và các trường chưa hoàn chỉnh.
6. Làm bài kiểm tra: Thực thi quy trình hoặc các bước nhất định với dữ liệu được kiểm soát.
7. Xem lại kết quả: Nó hiển thị các thông tin đầu vào, đầu ra, thời gian và các lỗi có thể xảy ra.
8. Xuất bản và kích hoạt: Chỉ thực hiện các thao tác này sau khi bạn đã xác nhận.

ActivePieces có thể tạo toàn bộ quy trình chỉ trong một thao tác, nhưng điều đó không có nghĩa là bạn nên xuất bản nó mà không xem xét lại. Hãy mở liên kết do trình hướng dẫn trả về và kiểm tra trực quan các kết nối, biểu thức và trường được sử dụng.

Nếu thiếu kết nối, trình hướng dẫn có thể cho bạn biết nơi cần cấu hình, nhưng bạn vẫn cần hoàn tất quy trình xác thực thông qua giao diện Activepieces. Thiết kế này giúp Kết nối các tác nhân AI với hệ thống nội bộ mà không cần tiết lộ thông tin đăng nhập..

Cách thức hoạt động của tìm kiếm hành động và kích hoạt

Chức năng Tìm kiếm công cụ Nó cho phép trợ lý ảo mô tả một tác vụ, chẳng hạn như "gửi tin nhắn đến kênh Slack", và nhận được các hành động phù hợp nhất từ ​​danh mục.

Quy trình khám phá gồm ba giai đoạn:

1. Phát hiện: Tìm kiếm các hành động hoặc yếu tố kích hoạt bằng cách sử dụng mô tả tự nhiên.
2. Thanh tra: Nó thu thập toàn bộ lược đồ và các trường của tùy chọn đã chọn.
3. Thực thi hoặc biên dịch: Sử dụng thao tác này một lần hoặc tích hợp nó vào quy trình làm việc liên tục.

Chức năng Tìm kiếm Công cụ đã được bật trong Activepieces Cloud. Đối với các cài đặt tự quản lý, bạn phải kích hoạt chức năng này bằng cách sử dụng biến sau:

AP_TOOL_SEARCH_ENABLED=true

Sự thay đổi được đọc một cách động và không yêu cầu khởi động lại phiên bản. Để có được kết quả ngữ nghĩa, Activepieces cũng yêu cầu một mô hình nhúng và một cơ sở dữ liệu PostgreSQL với phần mở rộng. pgvector.

Bạn có thể cung cấp khóa được sử dụng cho các embedding bằng cách:

AP_OPENAI_API_KEY=tu_clave

Bạn cũng có thể cấu hình OpenAI làm nhà cung cấp từ trang quản trị nền tảng. Nếu không có mô hình nhúng nào khả dụng hoặc việc lập chỉ mục ngữ nghĩa thất bại, chức năng Tìm kiếm Công cụ vẫn tiếp tục hoạt động bằng cách sử dụng từ khóa khớp.

Cách bảo vệ quyền truy cập Activepieces MCP

Máy chủ sử dụng OAuth, hạn chế các thao tác chỉ đối với dự án được ủy quyền và không trả lại các khóa hoặc mã thông báo đã lưu trữ cho máy khách. Tuy nhiên, việc bảo vệ bí mật không loại bỏ tất cả các rủi ro: một trình hướng dẫn với các công cụ thực thi có thể sử dụng gián tiếp các thông tin đăng nhập đó để thực hiện các hành động thực tế.

Hãy áp dụng các biện pháp này trước khi sử dụng MCP với các quy trình tự động hóa quy mô lớn:

• Hãy tạo một dự án riêng biệt để thử nghiệm ban đầu.
• Chỉ kích hoạt các danh mục công cụ thiết yếu.
• Sử dụng tài khoản ứng dụng với quyền hạn tối thiểu.
• Không cho phép đăng tải, xóa hoặc kích hoạt các luồng trừ khi thực sự cần thiết.
• Hãy yêu cầu xác nhận trước khi gửi tin nhắn hoặc chỉnh sửa dữ liệu bên ngoài.
• Kiểm tra cấu trúc thủ công trước khi xuất bản bản nháp.
• Xem lại quá trình thực thi và nhật ký sau mỗi thay đổi lớn.
• Thu hồi quyền ủy quyền OAuth nếu thiết bị hoặc máy khách không còn được sử dụng.

Đối với các quy trình tài chính, thay đổi CRM, liên lạc bên ngoài hoặc xóa thông tin, nên sử dụng phương pháp này. Thêm bước phê duyệt của con người vào quy trình làm việc của AI.Mô hình có thể chuẩn bị cho hoạt động, nhưng cần có người phê duyệt bước cuối cùng.

Tự lưu trữ cho phép bạn giữ Activepieces trong cơ sở hạ tầng của mình, nhưng không tự động đảm bảo tuân thủ quy định.Mức độ bảo mật tối ưu còn phụ thuộc vào máy chủ proxy, cơ sở dữ liệu, quyền truy cập, bản sao lưu và chính sách của tổ chức.

Cách cấu hình MCP phía sau máy chủ proxy ngược

Trong một cài đặt tự quản lý, địa chỉ công khai của Activepieces phải có thể truy cập được từ máy khách MCP và phải có HTTPS hợp lệ. Nếu phiên bản được công bố ở thư mục gốc của một tên miền, điểm cuối điển hình sẽ là:

https://automatizacion.example.com/mcp

Khi Activepieces nằm trong một tuyến con, bạn phải bao gồm nó trong AP_FRONTEND_URL:

AP_FRONTEND_URL=https://automatizacion.example.com/activepieces

Trong trường hợp này, máy chủ MCP sẽ có sẵn tại địa chỉ:

https://automatizacion.example.com/activepieces/mcp

Máy chủ proxy phải chuyển tiếp cả lưu lượng truy cập Activepieces và các điểm cuối được sử dụng trong quá trình ủy quyền OAuth. Một số máy khách tìm kiếm các tuyến đường. /.well-known/oauth-* trực tiếp tại thư mục gốc của tên miền. Nếu máy khách bỏ qua tiêu đề khám phá, bạn cần tạo thêm một quy tắc để chuyển tiếp các tuyến đường đó.

Không nên trực tiếp cho phép truy cập container thử nghiệm qua giao thức HTTP. Hãy sử dụng tên miền ổn định, TLS và cấu hình phù hợp. AP_FRONTEND_URLvì sự khác biệt giữa địa chỉ nội bộ và địa chỉ công khai có thể làm gián đoạn quá trình chuyển hướng OAuth.

Các lỗi thường gặp khi kết nối Activepieces với MCP

Máy khách cố gắng sử dụng mcp-remote hoặc địa chỉ kết thúc bằng /sse

Bạn đang làm theo hướng dẫn dành cho phiên bản cũ hơn. Máy chủ hiện tại được cấu hình bằng URL từ xa có đuôi là /mcpXóa lệnh cũ và đăng ký lại máy chủ.

Tùy chọn Máy chủ MCP chưa được kích hoạt.

Đi vào Cài đặt > Máy chủ MCPKích hoạt dịch vụ và sao chép lại địa chỉ. Đồng thời, kiểm tra xem bạn có đang làm việc trên đúng dự án hay không.

Quá trình xác thực OAuth rơi vào vòng lặp vô hạn.

Hãy kiểm tra xem địa chỉ công cộng có khớp chính xác hay không. AP_FRONTEND_URLNếu bạn đang sử dụng đường dẫn phụ, hãy xem lại các quy tắc proxy và điểm cuối khám phá OAuth.

Trợ lý chỉ có thể đọc các luồng dữ liệu.

Các công cụ khám phá chỉ có thể đọc dữ liệu. Hãy kích hoạt chúng một cách rõ ràng. Quản lý dòng chảy, Tòa nhà Flow hoặc một danh mục khác được yêu cầu từ cấu hình MCP của dự án.

Công cụ tìm kiếm cổ phiếu không hiển thị.

Trong trường hợp tự quản lý, hãy xác minh rằng AP_TOOL_SEARCH_ENABLED=trueNếu tìm kiếm thành công nhưng chỉ tìm thấy các kết quả trùng khớp chính xác, hãy kiểm tra nhà cung cấp nhúng và tính khả dụng của nó. pgvector.

Phù thủy tìm thấy một hành động, nhưng không thể thực hiện nó.

Quá trình tích hợp có thể yêu cầu kết nối chưa tồn tại hoặc đang gặp lỗi. Hãy mở Activepieces, cấu hình kết nối từ giao diện, sau đó yêu cầu thực thi lại.

Trợ lý đang làm nhầm dự án.

Hãy yêu cầu hệ thống hiển thị các dự án khả dụng và thiết lập ngữ cảnh chính xác. Các thao tác tiếp theo sẽ chỉ giới hạn trong dự án đó.

Luồng đã được tạo nhưng chưa hoạt động.

Kiểm tra xem nó còn ở dạng bản nháp, đã được xuất bản hay chưa, và trạng thái của nó là gì. Đã bậtNgoài ra, hãy kiểm tra xem trình kích hoạt có mẫu hợp lệ hay không và tất cả các kết nối có đang hoạt động hay không.

Bài kiểm tra hoạt động, nhưng quá trình thực thi thực tế lại thất bại.

Xem lại lịch sử thực thi và mở kết quả của từng bước. Quá trình kiểm thử có thể đã sử dụng dữ liệu mẫu khác với dữ liệu mà trình kích hoạt thực tế nhận được sau đó.

Người trợ lý đã chuẩn bị một kế hoạch hành động quá mạo hiểm.

Đừng chạy trực tiếp. Giảm số lượng danh mục được cho phép, sửa đổi lời nhắc để yêu cầu xác nhận và thêm bước phê duyệt của con người trước khi thực hiện bất kỳ thao tác không thể đảo ngược nào.

Việc kết nối ActivePieces với MCP biến trình hướng dẫn thành giao diện để xây dựng và duy trì các quy trình tự động hóa, nhưng theo mặc định, nó không cấp quyền truy cập không giới hạn. Máy chủ tách biệt các công cụ truy vấn khỏi khả năng ghi dữ liệu và giữ thông tin đăng nhập trong phạm vi dự án.

Quy trình thiết lập được đề xuất bao gồm kích hoạt máy chủ MCP, sao chép URL của nó, ủy quyền cho máy khách thông qua OAuth và bắt đầu với các công cụ chỉ đọc. Sau đó, bạn có thể dần dần kích hoạt các chức năng xây dựng, kiểm thử và xuất bản, xem xét từng quy trình làm việc trước khi sử dụng với dữ liệu hoặc tài khoản thực tế.