Warp + Scrapeless: Kết nối một máy chủ MCP từ xa

TL;DR:

• Warp kết nối với Scrapeless như một máy chủ MCP từ xa qua HTTP có thể phát trực tuyến. Một tệp .warp/.mcp.json ở gốc dự án của bạn với một tiêu đề url và x-api-token là toàn bộ cấu hình.
• Viết ${SCRAPELESS_API_KEY}, bao gồm cả dấu ngoặc. Warp mở rộng mẫu đó khi nó đọc tệp. $SCRAPELESS_API_KEY và {{SCRAPELESS_API_KEY}} đến được Scrapeless dưới dạng văn bản nguyên thủy, và máy chủ vẫn trông khỏe mạnh trong /mcp.
• Một biến chưa được đặt sẽ tạm dừng toàn bộ tệp. Mỗi máy chủ trong đó sẽ được thay thế bằng Warp config error … Missing or empty environment variable: SCRAPELESS_API_KEY.
• Máy chủ dự án khởi động bằng tay. Mở /mcp, chọn scrapeless và nhấn Enter; hàng di chuyển từ offline đến running · 25 tools.
• running · 25 tools không chứng minh khóa. Một khóa giả lập đạt cùng trạng thái. Một cuộc gọi công cụ, hoặc kiểm tra ngắn ở Bước 5, phân tách một khóa hợp lệ khỏi một khóa không hợp lệ.
• Tên tiêu đề là x-api-token. Một mục Authorization: Bearer thất bại với "từ chối thông tin xác thực đã cấu hình (HTTP 401)", ngay cả khi chính mã thông báo là hợp lệ.
• Nhận một khóa trên kế hoạch miễn phí của Scrapeless và thêm máy chủ trong vài phút.

Agent Warp chạy các lệnh trong một terminal thực sự và đọc mã của bạn, nhưng nó không có cái nhìn về những gì một trang web hiện đang hiển thị. Một máy chủ MCP khép lại khoảng trống đó: các công cụ mà tác nhân gọi giữa nhiệm vụ, được trả lời bởi một dịch vụ lấy và hiển thị trang cho nó.

Hướng dẫn này thêm máy chủ MCP được lưu trữ Scrapeless vào CLI Agent Warp, nhị phân warp. Cấu hình là một vài dòng JSON. Việc nó có hoạt động hay không phụ thuộc vào ba chi tiết: tệp nào Warp đọc, cách mà khóa được tham chiếu bên trong nó, và /mcp dòng trạng thái làm gì và không nói với bạn.

Những gì Scrapeless thêm vào phiên làm việc của Agent Warp

Máy chủ phơi bày 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 hiển thị 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.
• crawl_start, crawl_result và crawl_cancel thực hiện một cuộc thu thập trong nền và thu thập lại 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.

Không có gì chạy trên máy của bạn cho điều này. Vận chuyển HTTP có thể phát trực tuyến MCP là một điểm cuối HTTPS duy nhất nhận JSON-RPC qua POST, và Warp nói nó một cách tự nhiên. Nhật ký MCP của nó ghi lại MCP: Using Streaming HTTP transport cho máy chủ này mà không cần thiết lập vận chuyển nào trong tệp.

Nơi Warp tìm kiếm các định nghĩa máy chủ MCP

Warp đọc các định nghĩa máy chủ từ các tệp cấu hình cũng như từ trang cài đặt của nó. Tài liệu MCP của Warp liệt kê các vị trí này:

Máy chủ theo dự án từ bất kỳ nhà cung cấp nào không bao giờ tự khởi động. Warp phát hiện chúng và chờ bạn khởi động từng cái, và lựa chọn kéo dài chỉ trong phiên, vì vậy sau khi khởi động lại, bạn lại khởi động chúng lần nữa.

CLI cũng giữ một cấu hình tách biệt khỏi ứng dụng Warp. Trang cấu hình CLI của Warp Agent cung cấp ~/.warp_cli/.mcp.json như tệp đó trên macOS. Trên Linux, CLI Agent Warp v0.2026.09.09.08.26.stable_02 không nhận ra một máy chủ từ ~/.warp_cli/.mcp.json hoặc từ ~/.warp/.mcp.json, trong khi nó phát hiện cả ba tệp theo dự án và gán nhãn chúng Warp (.warp/.mcp.json), Claude (.mcp.json) và Other Agents (.agents/.mcp.json). Hướng dẫn này sử dụng .warp/.mcp.json, tệp mà Warp đặt tên là của nó.

Nếu bạn làm việc trong ứng dụng desktop Warp thay thế, cùng một mcpServers JSON sẽ được đưa vào Cài đặt > Tác nhân > Máy chủ MCP thông qua nút + Thêm.

Yêu cầu

• CLI Agent Warp, đã đăng nhập bằng tài khoản Warp. Hướng dẫn này sử dụng phiên bản v0.2026.09.09.08.26.stable_02, cái mà warp --version in ra.
• Tiền AI trên tài khoản Warp đó, cho bước khi tác nhân gọi một công cụ.
• Một khóa API Scrapeless từ bảng điều khiển Scrapeless.
• Một thư mục dự án để giữ tệp cấu hình. Các thử nghiệm ở đây đã sử dụng một kho Git.

Bước 1: Thêm .warp/.mcp.json vào Dự Án Của Bạn

Tạo .warp/.mcp.json trong thư mục gốc của dự án:

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "${SCRAPELESS_API_KEY}"
      }
    }
  }
}

Một máy chủ URL nhận hai thuộc tính trong Warp: url, là bắt buộc, và headers, một đối tượng key-value tùy chọn nói chung và bắt buộc ở đây, vì Scrapeless xác thực mọi yêu cầu bằng tiêu đề x-api-token. Không có trường type nào để thiết lập.

Tập tin giữ một tham chiếu biến, không phải một khóa, vì vậy nó có thể sống trong kiểm soát phiên bản. Mỗi người mở dự án xuất khóa của riêng họ. Điều đó giữ thông tin xác thực ra khỏi kho, điều mà hướng dẫn quản lý bí mật của OWASP coi là nơi mà một bí mật không nên tồn tại.

Bước 2: Xuất khẩu với Nơi giữ đúng

Xuất biến trong shell khởi động Warp, sau đó khởi chạy CLI từ thư mục dự án:

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
cd path/to/your-project
warp

Warp mở rộng ${VAR} tham chiếu khi nó đọc một tệp cấu hình từ đĩa. Hình thức quan trọng, và một hình thức sai sẽ thất bại trong im lặng. Mỗi biến thể dưới đây đã được gửi qua một proxy ghi nhật ký cục bộ để xem điều gì thực sự đến với Scrapeless:

Hai hàng thứ hai và thứ ba là chiếc bẫy. Chúng trông giống hệt như một thiết lập hoạt động cho đến khi cuộc gọi công cụ đầu tiên của tác nhân trả về lỗi xác thực.

Trường hợp chưa xuất khẩu thì lớn tiếng, nhưng nó phủ sóng xa hơn một máy chủ. Warp từ chối toàn bộ tệp và liệt kê một hàng lỗi đơn lẻ thay cho mỗi máy chủ được định nghĩa trong đó:

Warp config error  /path/to/your-project/.warp/.mcp.json · Missing or empty environment variable: SCRAPELESS_API_KEY

Trong quá trình kiểm tra, một máy chủ hợp lệ thứ hai được định nghĩa trong cùng một tệp cũng biến mất khỏi danh sách. Xuất biến trong hồ sơ shell của bạn, hoặc trong bất kỳ thứ gì khởi chạy các phiên terminal của bạn, để mỗi quy trình warp kế thừa nó.

Thiết lập điều này ngay bây giờ? Gói miễn phí Scrapeless 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: Khởi động Máy chủ Từ /mcp

Gõ /mcp trong đầu vào CLI để mở chế độ quản lý MCP, sau đó gõ scrapeless trong ô tìm kiếm của nó. Hàng đó đặt tên nhãn nhà cung cấp, dự án và phương thức vận chuyển:

scrapeless  Warp · scrapeless-demo · HTTP/SSE · offline

Nhấn Enter trên hàng. Trong vài giây, Warp thực hiện bắt tay MCP, liệt kê các công cụ và cập nhật hàng:

scrapeless  Warp · scrapeless-demo · HTTP/SSE · running · 25 tools

Nhấn Enter trên một hàng đang chạy dừng máy chủ. Vì các máy chủ theo phạm vi dự án là theo phạm vi phiên, lặp lại khởi động này mỗi lần bạn mở CLI trong dự án đó.

Bước 4: Đọc Trạng thái Trước Khi Bạn Nhắc Nhở

Mỗi trạng thái trong /mcp chỉ ra một bản sửa lỗi khác nhau:

Hàng failed xứng đáng được xem xét kỹ lưỡng, bởi vì lời khuyên của nó chỉ ra xa nguyên nhân. Với Authorization: Bearer ${SCRAPELESS_API_KEY} là tiêu đề, Warp ghi:

[error] MCP: Failed to connect to server: Transport creation error: MCP server 'scrapeless' rejected the configured credentials (HTTP 401). The request included the credential header(s) you configured, so the server did not accept that value — check the token itself, its expiry, and its scope. The server did not ask for OAuth.

Mã thông báo trong yêu cầu đó là hợp lệ. Scrapeless đã từ chối yêu cầu vì tên tiêu đề sai, và thân phản hồi của nó nói vậy: Unauthorized: Missing x-api-token header. Thay đổi tên tiêu đề và để khóa nguyên.

Warp ghi một tệp nhật ký cho mỗi lần khởi động máy chủ dưới ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp trên Linux. Mỗi tệp mở ra với một lời nhắc rằng nó có thể chứa thông tin nhạy cảm như khóa API, vì vậy hãy đọc nó cục bộ và xóa trước khi chia sẻ.

Bước 5: Chứng minh Khóa, Sau đó Nhắc Nhở Tác Nhân

Một máy chủ đang chạy với 25 công cụ chỉ cho thấy rằng một tiêu đề đã đến. Scrapeless trả initialize và tools/list cho bất kỳ giá trị khóa nào, bao gồm cả một giá trị bịa đặt. Sự khác biệt xuất hiện tại tools/call: với một khóa xấu, cuộc gọi vẫn trả lại HTTP 200, và văn bản kết quả bắt đầu bằng Failed to fetch data.

Kiểm tra này chạy cùng một bắt tay mà Warp chạy và sau đó gọi scrape_markdown một lần, không sử dụng gì ngoài thư viện tiêu chuẩn Python:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


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": "key-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 2, "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"])
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:60])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

Với một khóa hợp lệ đã được xuất, nó in ra:

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

Khi khóa được kiểm tra, đặt tên máy chủ và công cụ khi công việc là một lấy dữ liệu đơn lẻ:

Lưu ý: phiên bản tác nhân cần tín dụng AI trên tài khoản Warp của bạn, và nó không được chạy cho bài viết này vì tài khoản thử nghiệm không còn tín dụng; Warp đã trả lời "Bạn đã hết tín dụng AI." Khởi động máy chủ, bắt tay và kiểm tra khóa ở trên đều chạy chống lại cùng một điểm cuối với cùng một cấu hình.

Use the scrapeless MCP server's scrape_markdown tool to fetch
https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
and list the first three book titles with their prices.

Trên trang danh mục đó scrape_markdown trả về 8,940 ký tự trong khi scrape_html trả về 53,800, vì vậy Markdown tốn của tác nhân khoảng một phần sáu bối cảnh cho cùng một nội dung. Sử dụng scrape_html khi mã của bạn tự phân tích kết quả và scrape_markdown khi tác nhân đọc nó.

Các cuộc gọi công cụ MCP tuân theo hồ sơ thực thi hoạt động của bạn. mcp_permissions mặc định là agent_decides, và mcp_allowlist và mcp_denylist của hồ sơ nhận ID máy chủ MCP có thể chạy mà không cần phê duyệt hoặc phải luôn luôn hỏi.

Thông báo máy chủ MCP không scrapeless mô tả những gì máy chủ cung cấp, tài liệu MCP trình duyệt mang theo tham chiếu cấu hình, trang API Scraping đề cập đến các nhân vật đứng sau các công cụ, và giá cả liệt kê chi phí cho một cuộc gọi.

Kết luận

Bộ kết nối là một mục trong .warp/.mcp.json với ba điều kiện: tiêu đề có tên x-api-token, giá trị của nó là ${SCRAPELESS_API_KEY} với dấu ngoặc, và biến này được xuất ra trong shell khởi động warp. Sau đó, khởi động máy chủ từ /mcp một lần mỗi phiên.

Hai kết quả cần cẩn thận vì chúng trông ổn. Một kiểu giữ chỗ sai và một khóa sai đều hiển thị running · 25 tools, và chỉ có một cuộc gọi công cụ mới phơi bày chúng. Các thất bại hiển thị khác đọc khác nhau: một tiêu đề Bearer tạo ra failed … rejected the configured credentials, và một biến không được xuất ra sản xuất lỗi cấu hình ẩn giấu mọi máy chủ trong tệp.

Bạn đã sẵn sàng để cung cấp cho Tác nhân Warp một cái nhìn trực tiếp về web chưa? Bắt đầu với kế hoạch miễn phí Scrapeless và thêm máy chủ.

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

Q: Làm thế nào để tôi thêm một máy chủ MCP từ xa với tiêu đề khóa API vào Warp?

Tạo .warp/.mcp.json ở thư mục gốc dự án với một mục mcpServers có một url và một đối tượng headers, ví dụ "x-api-token": "${SCRAPELESS_API_KEY}". Xuất biến, khởi động warp trong thư mục đó, sau đó khởi động máy chủ từ /mcp. Trong ứng dụng desktop Warp, dán cùng một JSON dưới Cài đặt > Tác nhân > Máy chủ MCP > + Thêm.

Q: Warp có mở rộng biến môi trường trong tiêu đề MCP không?

Có, trong hình thức ${VAR}. Một giá trị tiêu đề của ${SCRAPELESS_API_KEY} đã đến máy chủ với khóa được xuất. $SCRAPELESS_API_KEY không có dấu ngoặc và {{SCRAPELESS_API_KEY}} đã được gửi dưới dạng văn bản nguyên văn.

Q: Tại sao máy chủ MCPWarp của tôi lại hiển thị đang chạy với một khóa API sai?

running · 25 tools có nghĩa là việc bắt tay và danh sách công cụ đã hoạt động, và Scrapeless trả lời cả hai cho bất kỳ giá trị khóa nào. Một khóa sai chỉ xuất hiện khi một công cụ chạy: cuộc gọi trả về văn bản bắt đầu bằng Failed to fetch data.

Q: Tại sao Warp lại nói rằng máy chủ MCP đã từ chối thông tin xác thực cấu hình?

Đối với Scrapeless, nguyên nhân thường gặp là tên tiêu đề, không phải token. Một tiêu đề Authorization: Bearer tạo ra rejected the configured credentials (HTTP 401), vì máy chủ tìm x-api-token và trả lời Missing x-api-token header.

Q: "Lỗi cấu hình Warp… Thiếu hoặc biến môi trường trống" có nghĩa là gì?

Tệp tham chiếu một biến mà không được thiết lập trong shell đã khởi động warp. Warp từ chối toàn bộ tệp, vì vậy mọi máy chủ được định nghĩa trong đó biến mất khỏi /mcp cho đến khi bạn xuất biến và khởi động lại CLI.

Q: Các máy chủ MCP theo phạm vi dự án có khởi động tự động trong Warp không?

Không. Warp phát hiện .warp/.mcp.json, .mcp.json và .agents/.mcp.json trong một dự án nhưng liệt kê máy chủ của chúng dưới dạng offline cho đến khi bạn khởi động từng cái từ /mcp, và lựa chọn đó chỉ kéo dài cho phiên hiện tại.

Q: Tại sao CLI Tác nhân Warp không liệt kê máy chủ của tôi từ ~/.warp_cli/.mcp.json?

Tài liệu CLI cung cấp đường dẫn đó cho macOS. Trên Linux, CLI Tác nhân Warp v0.2026.09.09.08.26.stable_02 không đọc ~/.warp_cli/.mcp.json hoặc ~/.warp/.mcp.json, và /mcp đã trả No matching MCP servers. Tệp dự án .warp/.mcp.json đã được phát hiện.

Q: Máy chủ MCP không scrapeless thêm bao nhiêu công cụ vào Warp?
25: ba scrape_* công cụ, mười sáu browser_* công cụ, ba crawl_* công cụ, cộng với google_search, google_trends và ai_scraper.