Composio + Scrapeless: Thêm bộ công cụ MCP tùy chỉnh

TL;DR:

• Scrapeless không có trong danh mục bộ công cụ của Composio, vì vậy nó tham gia như một bộ công cụ MCP tùy chỉnh. Bảng điều khiển của Composio có một hộp thoại Thêm MCP Tùy Chỉnh, được đánh dấu Beta, cho phép tạo một từ một máy chủ MCP từ xa.
• Hộp thoại nhận bốn giá trị. Một tên hiển thị, URL máy chủ https://api.scrapeless.com/mcp, khóa API là loại xác thực, và x-api-token là tên tiêu đề dưới Cài đặt Nâng cao.
• Để tiền tố tiêu đề trống. Scrapeless mong đợi khóa trần trong x-api-token. Với một tiền tố như token, quá trình bắt tay và danh sách 25 công cụ vẫn thành công, và mọi cuộc gọi công cụ đều thất bại.
• Composio kiểm tra xem một khóa đã được nhập, không phải là Scrapeless có chấp nhận nó hay không. Kiểm tra khóa và giá trị tiêu đề trước khi thêm bộ công cụ, và xác nhận với một cuộc gọi công cụ sau đó.
• Bộ công cụ thuộc về một dự án Composio. Thêm CUSTOM_ slug của nó vào một phiên, và truyền session.mcp.url cho bất kỳ khách hàng MCP nào.
• Nhận một khóa trên kế hoạch miễn phí Scrapeless và thêm bộ công cụ trong vài phút.

Các phiên Composio cung cấp cho một tác nhân công cụ được xác thực trên một danh sách dài các ứng dụng, với thông tin đăng nhập được giữ lại bên phía Composio. Điều một phiên không bao gồm là web trực tiếp, như một trang khi nó được hiển thị hôm nay hoặc kết quả của một tìm kiếm trên Google. Máy chủ Scrapeless MCP cung cấp những điều đó như các công cụ, và tính năng MCP Tùy Chỉnh của Composio cho phép một phiên gọi chúng bên cạnh các bộ công cụ tích hợp sẵn.

Hướng dẫn này thêm Scrapeless qua hộp thoại bảng điều khiển, sau đó sử dụng bộ công cụ trong một phiên. Hầu hết công việc là một biểu mẫu đơn. Phần cần chú ý là tiêu đề, vì một định dạng tiêu đề sai trông vẫn kết nối cho đến khi một công cụ thực sự chạy.

Tại sao Scrapeless tham gia Composio như một bộ công cụ MCP Tùy chỉnh

Danh mục của Composio chứa các bộ công cụ mà Composio xuất bản, và Scrapeless không phải là một trong số đó. Đối với một dịch vụ bên ngoài danh mục, hướng dẫn MCP Tùy Chỉnh của Composio mô tả con đường. Bạn đăng ký một máy chủ MCP từ xa qua URL HTTPS công khai và cơ chế xác thực của nó, và Composio tạo một bộ công cụ với CUSTOM_ slug, đồng bộ hóa các công cụ của máy chủ và chuyển tiếp mỗi cuộc gọi công cụ đến máy chủ với thông tin đăng nhập của tài khoản đã kết nối.

Ba giới hạn đi kèm với nó. MCP Tùy Chỉnh là thử nghiệm, và Composio nói rằng quy trình thiết lập và hợp đồng của nó có thể thay đổi. Bộ công cụ được giới hạn cho dự án Composio đã đăng ký nó. Và Composio không lưu trữ máy chủ, vì vậy máy chủ phải có thể truy cập qua HTTPS; Scrapeless là một điểm cuối được lưu trữ, vì vậy không có gì chạy trên máy của bạn.

Hướng dẫn tương tự vẫn mô tả việc đăng ký chỉ cung cấp API và liệt kê quản lý bảng điều khiển là sẽ có sớm. Bảng điều khiển Composio vào tháng 9 năm 2026 đã cho thấy một hộp thoại Thêm MCP Tùy Chỉnh, được gán nhãn Beta và Chỉ MCP, và hộp thoại đó là con đường mà hướng dẫn này theo dõi. Lộ trình API được đề cập trong câu hỏi thường gặp.

Những gì Scrapeless thêm vào một phiên Composio

Máy chủ cung cấp 25 công cụ, được nhóm theo công việc:

• scrape_markdown, scrape_html và scrape_screenshot trả về một trang đã được kết xuất dưới dạng Markdown, HTML thô hoặc một hình ảnh trong một cuộc gọi.
• Mười sáu công cụ browser_*, từ browser_create và browser_goto đến browser_click, browser_type và browser_snapshot, điều khiển một phiên trình duyệt đám mây từng bước một.
• crawl_start, crawl_result và crawl_cancel thực hiện một cuộc thu thập thông tin trong nền và thu thập nó sau.
• google_search và google_trends trả về kết quả tìm kiếm và dữ liệu xu hướng, và ai_scraper thu thập câu trả lời từ các trợ lý AI như ChatGPT, Gemini và Perplexity.

Tất cả 25 công cụ đến như một bộ công cụ. Trong một phiên mặc định, hướng dẫn của Composio nói rằng một tác nhân phát hiện các công cụ tùy chỉnh thông qua tìm kiếm công cụ của nó và chạy chúng qua Bộ chuyển hướng Công cụ, theo cách mà nó tiếp cận các bộ công cụ tích hợp sẵn.

Điều kiện tiên quyết

• Tài khoản Composio với một dự án. Các bộ công cụ MCP Tùy Chỉnh thuộc về một dự án.
• Một khóa API Scrapeless từ bảng điều khiển Scrapeless. Một khóa chỉ phục vụ Composio có thể được xoay vòng mà không làm ảnh hưởng đến những tích hợp khác của bạn.
• Python 3 cho việc kiểm tra trong Bước 1, sử dụng chỉ thư viện tiêu chuẩn.
• Đối với Bước 4, SDK Python của Composio (hướng dẫn này đã sử dụng composio 0.21.1) và khóa API của dự án Composio của bạn. Mã phiên của Bước 4 chưa được chạy chống lại một dự án Composio cho hướng dẫn này.

Bước 1: Kiểm tra Khóa và Giá trị Tiêu đề

Hướng dẫn của Composio liệt kê một khoảng trống đã biết đáng để lập kế hoạch: khi bạn kết nối một máy chủ khóa API, thiết lập kiểm tra xem một khóa đã được cung cấp, không phải là máy chủ từ xa chấp nhận nó. Scrapeless thêm một điểm mù thứ hai, vì nó trả lời quá trình bắt tay MCP và liệt kê các công cụ của nó cho bất kỳ giá trị khóa nào. Một khóa sai hoặc một định dạng tiêu đề sai chỉ xuất hiện khi một công cụ chạy.
Kịch bản này gửi các yêu cầu mà một khách hàng MCP gửi, với khóa trong tiêu đề x-api-token, liệt kê các công cụ và sau đó gọi scrape_markdown một lần. Nó tuân theo vận chuyển HTTP có thể phát streaming MCP, JSON-RPC qua POST đến một điểm cuối duy nhất, và không cần gì hơn thư viện tiêu chuẩn Python:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
PREFIX = os.environ.get("HEADER_PREFIX", "")
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": f"{PREFIX} {os.environ['SCRAPELESS_API_KEY']}".strip(),
}


def post(payload, session_id=None):
    headers = dict(HEADERS)
    if session_id:
        headers["Mcp-Session-Id"] = session_id
    request = urllib.request.Request(URL, data=json.dumps(payload).encode(), headers=headers)
    with urllib.request.urlopen(request, timeout=120) as response:
        body = response.read().decode()
        session_id = response.headers.get("Mcp-Session-Id") or session_id
    events = [line[5:].strip() for line in body.splitlines() if line.startswith("data:")]
    return session_id, json.loads(events[-1]) if events else None


session, init = post({
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
               "clientInfo": {"name": "header-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, listing = post({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "scrape_markdown", "arguments": {"url": "https://example.com"}},
}, session)

server = init["result"]["serverInfo"]
text = "".join(part.get("text", "") for part in result["result"]["content"])
print(server["name"], server["version"])
print("tools listed:", len(listing["result"]["tools"]))
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:20])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

Với khóa của bạn được xuất ra dưới dạng SCRAPELESS_API_KEY, nó in ra:

scrapeless-mcp-server 0.2.0
tools listed: 25
key accepted: 184 characters of Markdown

Bây giờ xuất HEADER_PREFIX=token và chạy lại. Kịch bản đặt token và một khoảng trống trước khóa, hình dạng mà giá trị tiêu đề có tiền tố lấy:

scrapeless-mcp-server 0.2.0
tools listed: 25
key rejected: Failed to fetch data

Cuộc bắt tay và số lượng công cụ là giống nhau trong cả hai lần chạy. Chỉ có cuộc gọi công cụ mới phân biệt chúng, và Bearer với tư cách là tiền tố cũng thất bại theo cách tương tự.

Bước 2: Thêm Scrapeless Với Thêm MCP Tùy Chỉnh

Trong bảng điều khiển Composio, mở Thêm MCP Tùy Chỉnh, hộp thoại có tiêu đề "Tạo một bộ công cụ từ một máy chủ MCP từ xa", và điền vào:

Sau đó chọn Thêm.

Tiền tố tiêu đề là trường cần lưu ý. Nó tồn tại cho các API mà mong đợi một từ cấu trúc đứng trước thông tin xác thực, chẳng hạn như Bearer. Scrapeless đọc toàn bộ giá trị x-api-token như khóa, vì vậy bất kỳ tiền tố nào làm cho một khóa hợp lệ thành một khóa mà nó từ chối, như lần chạy thứ hai trong Bước 1 đã chỉ ra.

Đảm bảo các cài đặt này đúng trước khi bạn lưu. Trong API của Composio, định dạng tiêu đề là một phần của cấu trúc xác thực của bộ công cụ, và hướng dẫn MCP Tùy Chỉnh nói rằng URL máy chủ và cấu trúc xác thực không thể thay đổi sau khi đăng ký; một nỗ lực trả về 409 Conflict. Để sửa một bộ công cụ đã được lưu với một tiền tố, hãy sử dụng Xóa trên trang của nó và thêm lại. Xóa một bộ công cụ tùy chỉnh cũng xóa các cấu hình xác thực và tài khoản liên kết của nó, vì vậy bạn kết nối lại tài khoản sau đó.

Cài đặt điều này ngay bây giờ? Kế hoạch Scrapeless miễn phí bao gồm kết nối và các cuộc gọi công cụ đầu tiên của bạn.

Bước 3: Kết Nối Tài Khoản và Để Các Công Cụ Đồng Bộ

Một bộ công cụ khóa API không có gì để gọi cho đến khi một tài khoản được kết nối, và đây là nơi mà khóa đi vào. Tiền tố tiêu đề trống từ Bước 2 chỉ có nghĩa là không có gì được đặt trước khóa. Kết nối mở một trang có tiêu đề "Composio muốn kết nối với của bạn" theo sau là tên của bộ công cụ, với một trường Khóa API yêu cầu duy nhất. Dán khóa API Scrapeless của bạn ở đó và chọn Kết Nối Tài Khoản. Composio lưu trữ khóa trên tài khoản đã kết nối và đặt nó trong tiêu đề x-api-token của mọi yêu cầu nó gửi đến Scrapeless.

Việc đồng bộ lần đầu tiên bắt đầu trong nền khi tài khoản đó trở nên hoạt động. Quay lại trang Scrapeless, Tài Khoản Kết Nối liệt kê tài khoản là Hoạt Động, và Hành Động Có Sẵn hiển thị 25, một cho mỗi công cụ Scrapeless, dưới các tên như "Ai scraper" và "Nhấp chuột Trình duyệt". Những kết nối sau không đồng bộ bộ công cụ lại, vì vậy khi Scrapeless thêm công cụ, hãy sử dụng Đồng Bộ trên trang đó. Một bộ công cụ tùy chỉnh giữ tối đa 500 công cụ.

Một danh sách công cụ đã đồng bộ chứng minh Composio đã đến được máy chủ. Nó không chứng minh khóa, vì lý do mà Bước 1 đã chỉ ra, đó là lý do tại sao bước cuối cùng kết thúc bằng một cuộc gọi công cụ.

Khóa bây giờ cũng sống với một bên thứ ba. Hướng dẫn quản lý bí mật OWASP coi việc xoay vòng là thường lệ, và một khóa dành riêng cho Composio là khóa bạn có thể xoay mà không làm hỏng bất cứ điều gì khác.

Bước 4: Sử Dụng Bộ Công Cụ Trong Một Phiên

Thêm slug của bộ công cụ vào một phiên. Với mcp=True, phiên cũng lộ diện một máy chủ MCP được lưu trữ mà bất kỳ khách hàng MCP nào cũng có thể sử dụng.

Lưu ý: mã này theo SDK Python Composio 0.21.1 và hướng dẫn phiên của Composio; nó chưa được chạy chống lại một dự án Composio cho hướng dẫn này. Nó cần COMPOSIO_API_KEY được đặt thành khóa API dự án của bạn.

from composio import Composio

composio = Composio()  # reads COMPOSIO_API_KEY from the environment

session = composio.sessions.create(
    user_id="user_123",
    toolkits=["CUSTOM_SCRAPELESS"],
    connected_accounts={"CUSTOM_SCRAPELESS": ["ca_your_connected_account_id"]},
    mcp=True,
)

print(session.mcp.url)

Sử dụng slug hiển thị trên trang bộ công cụ của bạn nếu nó khác với CUSTOM_SCRAPELESS; Composio thêm tiền tố CUSTOM_ khi nó đăng ký bộ công cụ. Mục connected_accounts gán tài khoản mà các cuộc gọi chạy như. Các phiên khớp với tài khoản bằng user_id riêng lẻ khi cấu hình xác thực của bộ công cụ có tính năng khớp bộ định tuyến công cụ được kích hoạt, và nếu không thì các cuộc gọi thất bại với NoActiveConnection. Gán tài khoản hoạt động theo cả hai cách.
Hướng dẫn của Composio về các phiên qua MCP truyền session.mcp.url và session.mcp.headers đến cấu hình MCP của khách hàng, cho các khung như OpenAI Agents SDK và Claude Agent SDK. Các tiêu đề mang thông tin xác thực cho URL đó, vì vậy hãy chuyển chúng cho khách hàng mà không ghi lại.

Sau đó, hãy giao cho đại lý một công việc có thể kiểm tra:

Use the Scrapeless scrape_markdown tool to fetch https://example.com
and reply with the first heading of the returned page, quoted exactly.

Một thiết lập hoạt động trả lời với "# Example Domain". Một phản hồi trích dẫn Failed to fetch data sẽ chỉ về khóa hoặc tiền tố tiêu đề.

Sửa các sự cố phổ biến

Để biết thêm về những gì máy chủ cung cấp, hãy đọc thông báo máy chủ MCP không Scrapeless. Tài liệu MCP trình duyệt chứa tham chiếu cấu hình, trang API Scraping đề cập đến các tác nhân đứng sau các công cụ, và danh sách giá cả liệt kê chi phí của mỗi cuộc gọi.

Kết luận

Thêm Scrapeless vào Composio chỉ cần một cuộc đối thoại: tên hiển thị, https://api.scrapeless.com/mcp, xác thực khóa API, x-api-token làm tên tiêu đề và một tiền tố tiêu đề trống. Kết nối một tài khoản với khóa của bạn, để các công cụ đồng bộ, và thêm bộ công cụ CUSTOM_ vào một phiên.

Những gì cần quan tâm là khoảng cách giữa việc đồng bộ và hoạt động. Composio xác nhận rằng một khóa đã được nhập, và Scrapeless liệt kê công cụ của nó cho bất kỳ khóa nào, vì vậy một lỗi tiền tố sẽ vượt qua cả hai kiểm tra. Chạy kiểm tra khóa trước khi bạn thêm bộ công cụ và một cuộc gọi công cụ thật sự sau đó, và thiết lập sẽ được chứng minh đầy đủ.

Sẵn sàng để cho các đại lý Composio của bạn có cái nhìn trực tiếp về web? Bắt đầu với kế hoạch dùng thử miễn phí Scrapeless và thêm bộ công cụ.

Câu hỏi thường gặp

Q: Tôi có thể thêm một máy chủ MCP tùy chỉnh vào Composio không?

Có. MCP tùy chỉnh đăng ký một máy chủ từ xa qua URL HTTPS và sơ đồ xác thực của nó và biến nó thành một bộ công cụ có phạm vi dự án với một CUSTOM_ slug. Bảng điều khiển có một hộp thoại Thêm MCP tùy chỉnh cho nó, và API của Composio cung cấp cùng một đăng ký thông qua các điểm cuối bộ công cụ tùy chỉnh của nó.

Q: Điều gì đi vào tiền tố tiêu đề cho Scrapeless?

Không có gì. Đặt tên tiêu đề là x-api-token và để tiền tố trống, vì Scrapeless đọc toàn bộ giá trị tiêu đề như là khóa. Một tiền tố token hoặc Bearer sẽ khiến mỗi cuộc gọi công cụ thất bại ngay cả khi các công cụ vẫn đồng bộ.

Q: Tôi nhập khóa API Scrapeless ở đâu trong Composio?

Trên trang kết nối, khi bạn kết nối một tài khoản trên bộ công cụ. Hộp thoại Thêm MCP tùy chỉnh chỉ định tên tiêu đề và tiền tố; trang kết nối yêu cầu Khóa API, và Composio gửi giá trị đó như tiêu đề x-api-token.

Q: Tại sao các công cụ Scrapeless của tôi đồng bộ trong Composio nhưng mỗi cuộc gọi đều thất bại?

Danh sách công cụ hoạt động với bất kỳ giá trị khóa nào, vì vậy một bộ công cụ đồng bộ không chứng minh được thông tin xác thực. Các cuộc gọi trả về Failed to fetch data có nghĩa là giá trị tiêu đề sai: một Tiền tố tiêu đề đã điền hoặc một khóa không hợp lệ. Chạy kiểm tra từ Bước 1 với khóa của bạn để xem cái nào.

Q: Tôi có thể thay đổi cài đặt tiêu đề sau khi thêm bộ công cụ không?

Không thể thay đổi ngay tại chỗ. Composio coi URL máy chủ và sơ đồ xác thực là cố định sau khi đăng ký. Xóa bộ công cụ, thêm nó lại với cài đặt đúng, và kết nối lại tài khoản, vì việc xóa sẽ loại bỏ các kết nối của nó.

Q: Tôi có thể đăng ký Scrapeless thông qua API của Composio thay vì bảng điều khiển không?
Có. POST /api/v3.1/custom/toolkits/upsert lấy URL máy chủ và một API_KEY sơ đồ xác thực với một đối tượng headers. Composio cho phép tên tiêu đề khác ngoài Authorization miễn là một giá trị tiêu đề chứa {{generic_api_key}}, vì vậy mục cho Scrapeless là "x-api-token": "{{generic_api_key}}". Đối với các máy chủ API-key, hướng dẫn thêm một bước cấu hình xác thực riêng biệt trước khi các tài khoản có thể kết nối.

Q: Bộ công cụ Scrapeless có sẵn trong tất cả các dự án Composio của tôi không?

Không. Bộ công cụ MCP tùy chỉnh chỉ áp dụng cho dự án đã đăng ký nó. Thêm Scrapeless vào mỗi dự án cần nó.

Q: Claude, Cursor hoặc một khách hàng MCP khác có thể sử dụng Scrapeless thông qua Composio không?

Có. Tạo một phiên với mcp=True và cung cấp cho khách hàng session.mcp.url và session.mcp.headers. Khách hàng sau đó truy cập các công cụ Scrapeless thông qua phiên Composio.

Q: Scrapeless thêm bao nhiêu công cụ vào Composio?

25: ba công cụ scrape_*, mười sáu công cụ browser_*, ba công cụ crawl_*, cộng với google_search, google_trends và ai_scraper.