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

TL;DR:

• OpenCode coi Scrapeless là một remote máy chủ MCP trong opencode.json. Mục nhập cần một url, một tiêu đề x-api-token và "oauth": false.
• Viết khóa dưới dạng {env:SCRAPELESS_API_KEY}, không phải ${SCRAPELESS_API_KEY}. OpenCode thay thế dạng đầu tiên và gửi dạng thứ hai dưới dạng văn bản nguyên văn, và máy chủ vẫn liệt kê như đã được kết nối trong khi mọi lệnh gọi công cụ đều thất bại với mã 401.
• ✓ connected chỉ chứng minh tiêu đề có mặt. Bắt tay Scrapeless chấp nhận bất kỳ giá trị x-api-token nào và vẫn liệt kê tất cả 25 công cụ, vì vậy hãy đọc một kết quả công cụ trước khi tin tưởng vào thiết lập.
• Cài đặt oauth quyết định cách một lỗi Bearer trông như thế nào. Để ở mặc định của nó, một tiêu đề Authorization: Bearer hiển thị ⚠ needs authentication; với "oauth": false, cùng tiêu đề đó hiển thị ✗ failed với mã 401.
• Các công cụ được đặt tên <server>_<tool>. Một mục nhập máy chủ gọi scrapeless cung cấp mô hình scrapeless_scrape_markdown, và 25 định nghĩa quay trở lại dưới dạng phản hồi tools/list khoảng 30 KB.
• Lấy một key trên kế hoạch miễn phí Scrapeless và kết nối OpenCode trong vài phút.

OpenCode chạy một đại lý mã hóa trong terminal của bạn chống lại bất kỳ nhà cung cấp mô hình nào bạn cấu hình. Nó đọc các tệp và thực thi các lệnh, nhưng một câu hỏi về một trang web trực tiếp cần một công cụ thu thập một trang, và máy chủ MCP là cách OpenCode lấy các công cụ mà nó không cung cấp.

Máy chủ MCP Scrapeless được lưu trữ, vì vậy việc kết nối nó là cấu hình chứ không phải cài đặt. Hướng dẫn này đề cập đến mục nhập cấu hình, cú pháp thay thế mà bị quên lặng lẽ, ý nghĩa của từng trạng thái opencode mcp list và cách phân biệt một khóa hoạt động từ một máy chủ chỉ kết nối.

Những Gì OpenCode Nhận Từ Scrapeless

Máy chủ liệt kê 25 công cụ. Ba công cụ trả về một trang trong một lần gọi: scrape_markdown, scrape_html và scrape_screenshot. Mười sáu browser_* công cụ, như browser_create, browser_goto, browser_click và browser_type, điều khiển một phiên duyệt web đám mây từng bước một. crawl_start, crawl_result và crawl_cancel quản lý một tiến trình thu thập, và google_search, google_trends và ai_scraper hoàn thành bộ công cụ.

Đối với hầu hết các yêu cầu, công cụ hữu ích nhất là scrape_markdown. Nó trả về trang đã được hiển thị dưới dạng Markdown, đó là hình thức mà một mô hình đọc với giá thành thấp nhất, và nó không cần gì ngoài một URL.

Điều Kiện Tiên Quyết

• OpenCode, với một nhà cung cấp mô hình đã được cấu hình. Hướng dẫn này sử dụng OpenCode 1.17.19.
• Một khóa API Scrapeless từ bảng điều khiển Scrapeless.
• Không cần cài đặt gì cho máy chủ. Nó chạy tại https://api.scrapeless.com/mcp và OpenCode tiếp cận nó qua HTTP.

Bước 1: Thêm Máy Chủ vào opencode.json

OpenCode đọc các máy chủ MCP từ khối mcp của cấu hình của nó. Tệp toàn cục là ~/.config/opencode/opencode.json, và một opencode.json trong gốc dự án áp dụng cho dự án đó:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scrapeless": {
      "type": "remote",
      "url": "https://api.scrapeless.com/mcp",
      "oauth": false,
      "headers": {
        "x-api-token": "{env:SCRAPELESS_API_KEY}"
      }
    }
  }
}

"type": "remote" khiến OpenCode kết nối qua HTTP thay vì khởi động một lệnh cục bộ. "oauth": false ngăn nó bắt đầu một quy trình OAuth, điều mà điểm cuối Scrapeless không cung cấp; các đường dẫn khám phá OAuth của nó trả về mã 404, và nó xác thực chỉ dựa vào tiêu đề. opencode mcp add cũng có thể viết một mục nhập và chấp nhận các cờ --url và --header, nhưng chỉnh sửa tệp trực tiếp là cách đáng tin cậy để có được tham chiếu {env:} đúng chính xác.

Bước 2: Sử Dụng Thay Thế {env:}, Không ${}

OpenCode thay thế {env:VARIABLE_NAME} với giá trị của biến môi trường đó khi nó tải cấu hình. Các biến môi trường là nơi thường được dùng cho các thông tin xác thực thay đổi giữa các máy, sự tách biệt tương tự mà hướng dẫn cấu hình ứng dụng Twelve-Factor khuyến nghị, và {env:} là cách OpenCode đọc chúng. Xuất khóa trong shell bắt đầu OpenCode:

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
opencode mcp list

●  ✓ scrapeless connected
│      https://api.scrapeless.com/mcp

Kiểu ${SCRAPELESS_API_KEY} như kiểu shell trông giống nhau nhưng không phải. OpenCode truyền nó qua dưới dạng văn bản nguyên văn, và vì bắt tay Scrapeless chấp nhận bất kỳ token không rỗng nào, máy chủ vẫn liệt kê ✓ connected. Vấn đề chỉ xuất hiện khi mô hình gọi một công cụ:

Failed to fetch data. Error: [Scrapeless]: Request POST /api/v1/unlocker/request failed with status 401

Để biến không được xuất lại thất bại sớm và rõ rệt hơn. Với {env:SCRAPELESS_API_KEY} chỉ vào không gì, chính quá trình bắt tay bị từ chối:

●  ✗ scrapeless failed
│      SSE error: Non-200 status code (401)
│      https://api.scrapeless.com/mcp

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

Bước 3: Đọc Từng Trạng Thái Danh Sách mcp opencode

Dòng trạng thái cho biết liệu OpenCode có thể mở kết nối hay không. Nó không cho biết liệu khóa có hoạt động hay không.

Một chế độ lỗi đọc như một khóa xấu nhưng không phải vậy. Nếu dòng trạng thái nói rằng đã kết nối và một cuộc gọi công cụ trả Failed to fetch data, kiểm tra xem có một máy chủ MCP khác trên máy có công cụ Scrapeless giống như vậy, chẳng hạn như một gateway mà định tuyến nhiều nhà cung cấp sau một thông tin xác thực. Đại lý có thể đã gọi cái đó thay vì. OpenCode gán tiền tố cho mỗi công cụ bằng tên máy chủ của nó, vì vậy dòng biên dịch nêu tên máy chủ đã trả lời.

Hầu hết các ví dụ MCP xác thực với Authorization: Bearer, sơ đồ các thông số cho mã thông báo bearer OAuth 2.0 định nghĩa. Scrapeless đọc x-api-token thay vào đó, vì vậy một tiêu đề Bearer kiếm được một phản hồi 401 Unauthorized. Với oauth ở mặc định của nó, OpenCode coi mã 401 đó như là một lời nhắc để đăng nhập:

●  ⚠ scrapeless needs authentication
│      https://api.scrapeless.com/mcp

Với "oauth": false, tiêu đề giống nhau đọc ✗ failed với mã 401, mô tả một tiêu đề sai chính xác hơn là một lời mời xác thực.

Bước 4: Gọi một Công Cụ từ một Lời Nhắc

Đặt tên máy chủ và công cụ lần đầu tiên, để kết quả chỉ có một nguồn khả dĩ:

Use the scrapeless MCP server's scrape_markdown tool on https://example.com
and reply with the first markdown heading line.

opencode run --format json in ra từng bước như một sự kiện JSON. Sự kiện công cụ từ lời nhắc đó:

type: tool_use
tool: scrapeless_scrape_markdown
status: completed
output: Response: "# Example Domain\n\nThis domain is for use in documentation ...

Phản hồi của mô hình là # Example Domain. Tên công cụ theo mẫu <server>_<tool> của OpenCode, vì vậy một mục gọi là scrapeless đặt cùng một tiền tố cho tất cả 25 công cụ.

Đầu ra đó là kiểm tra opencode mcp list không thể gửi cho bạn. Một kết quả bắt đầu với nội dung trang có nghĩa là khóa hoạt động. Một kết quả bắt đầu với Failed to fetch data có nghĩa là kết nối ổn và khóa không hoạt động. Các thông số công cụ MCP cung cấp một cờ isError cho các cuộc gọi thất bại, nhưng Scrapeless trả về cả hai kết quả như văn bản công cụ bình thường mà không có nó, vì vậy văn bản là thứ cần đọc.

Mỗi máy chủ kết nối cũng thêm các định nghĩa công cụ của nó vào ngữ cảnh của mô hình, và phản hồi tools/list Scrapeless cho tất cả 25 công cụ khoảng 30 KB. Đặt "enabled": false trên mục giữ cho nó được cấu hình nhưng ra khỏi các phiên không cần web.

Đối với những gì máy chủ tiết lộ, Thông báo MCP server Scrapeless đề cập đến việc ra mắt, và hướng dẫn tích hợp MCP của chúng tôi so sánh các cách mà đại lý tiếp cận trình duyệt. Tài liệu MCP trình duyệt mang tham chiếu cấu hình, trang API Scraping mô tả 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

OpenCode cần bốn điều từ mục: "type": "remote", URL Scrapeless, một tiêu đề x-api-token được viết như {env:SCRAPELESS_API_KEY}, và "oauth": false. Cú pháp thay thế là chi tiết có khả năng sai nhất, vì hình thức bị hỏng vẫn kết nối.

opencode mcp list bắt lỗi tiêu đề bị thiếu, một biến không xuất khẩu và sự nhầm lẫn Bearer. Chỉ một kết quả công cụ bắt được một khóa xấu, vì vậy hãy thực hiện một cuộc gọi và đọc những gì trở về trước khi xây dựng bất cứ thứ gì trên kết nối.

Sẵn sàng để đưa OpenCode một cái nhìn trực tiếp về web? 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 đề API key vào OpenCode?

Thêm một mục dưới mcp trong opencode.json với "type": "remote", máy chủ url, "oauth": false và một đối tượng headers. Đối với Scrapeless, tiêu đề là x-api-token, được viết như {env:SCRAPELESS_API_KEY} để khóa không nằm trong tệp.

Q: Tại sao ${SCRAPELESS_API_KEY} không hoạt động trong opencode.json?
Cú pháp thay thế của OpenCode là {env:SCRAPELESS_API_KEY}. Hình thức kiểu shell được gửi dưới dạng văn bản nguyên văn, vì vậy máy chủ vẫn hiển thị là đã kết nối và các lệnh công cụ quay trở lại với failed with status 401.

Q: Tại sao danh sách mcp của opencode lại cần xác thực?

Máy chủ đã trả về mã 401 trong khi oauth được kích hoạt, vì vậy OpenCode yêu cầu đăng nhập. Đối với Scrapeless, điều này gần như luôn có nghĩa là một tiêu đề Authorization: Bearer; chuyển sang x-api-token và đặt "oauth": false.

Q: Liệu "đã kết nối" có nghĩa là khóa Scrapeless của tôi hợp lệ?

Không. Việc bắt tay Scrapeless và danh sách công cụ thành công với bất kỳ giá trị x-api-token nào không trống. Chỉ một lệnh công cụ mới tiết lộ một khóa không tốt, vì kết quả bắt đầu bằng Failed to fetch data.

Q: Tên các công cụ Scrapeless bên trong OpenCode là gì?

OpenCode đặt tên cho các công cụ MCP là <server>_<tool>. Với mục gọi là scrapeless, mô hình thấy scrapeless_scrape_markdown và cùng tiền tố trên 24 công cụ khác.

Q: OpenCode đọc opencode.json từ đâu?

Cấu hình toàn cục là ~/.config/opencode/opencode.json, và một dự án có thể thêm opencode.json riêng của nó vào thư mục gốc. Biến môi trường OPENCODE_CONFIG chỉ OpenCode đến một tệp cấu hình cụ thể thay thế.

Q: Tôi có cần cài đặt một gói cho máy chủ Scrapeless MCP không?

Không. Máy chủ được lưu trữ tại https://api.scrapeless.com/mcp, và OpenCode kết nối với nó qua HTTP, vì vậy không có gói nào, không có quy trình cục bộ và không có phiên bản nào cần cập nhật.