MCP Server

Sử dụng FourA từ bất kỳ client Model Context Protocol nào (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) dưới dạng bốn công cụ native và sáu workflow prompt. Không cần mã tích hợp, không cần HTTP client tùy chỉnh.

Mã nguồn mở trên GitHub; trên npm dưới tên @fouradata/mcp. Bản phát hành hiện tại: 0.5.0.

Bắt đầu nhanh: stdio cục bộ (được đề xuất cho Claude Desktop)

Lấy khóa tại foura.ai/dashboard#api-keys (nhấp một lần, chỉ hiển thị một lần khi tạo, định dạng pk_live_...). Thêm phần này vào cấu hình client MCP của bạn:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}

Lưu ý về Claude Desktop: hãy thoát hoàn toàn Claude Desktop (Cmd+Q trên macOS) trước khi chỉnh sửa tệp cấu hình. Nếu ứng dụng vẫn đang chạy, nó sẽ ghi đè các chỉnh sửa của bạn bằng cấu hình trong bộ nhớ khi thoát.

Lệnh npx sẽ tải xuống @fouradata/mcp trong lần khởi chạy đầu tiên và chạy nó dưới dạng một tiến trình con của MCP client. Không cần cài đặt toàn cục.

Client	Vị trí tệp cấu hình
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Claude Code	`claude mcp add foura -- npx -y @fouradata/mcp` (đặt `FOURA_API_KEY` trong biến môi trường trước)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (MCP extension)	`.vscode/mcp.json`

Khởi động lại client. Các công cụ (foura_auto, foura_single, foura_proxy, foura_browser) và sáu prompt sẽ xuất hiện trong danh sách công cụ của bạn.

Bắt đầu nhanh: hosted (Streamable HTTP)

Đối với các client hỗ trợ Streamable HTTP transport (Cursor, Windsurf, VS Code, Claude Code với --transport http), hãy trỏ chúng đến hosted endpoint thay vì chạy một tiến trình con cục bộ:

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

Đối với Claude Desktop, hãy sử dụng cấu hình stdio ở trên hoặc kết nối endpoint được lưu trữ thông qua mcp-remote:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

Tham chiếu endpoint được lưu trữ

Thuộc tính	Giá trị
URL	`https://mcp.foura.ai/mcp`
Transport	Streamable HTTP (POST `/mcp`, phản hồi SSE)
Xác thực	`Authorization: Bearer pk_live_...` cho mỗi request
MCP-Protocol-Version	Theo `@modelcontextprotocol/sdk` (hiện tại là `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`)
Challenge 401	`WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

Server được lưu trữ là stateless. Mỗi request mang theo key riêng, key này được server chuyển tiếp đến FourA API dưới dạng X-API-Key. Một key có thể mở cả bốn tool.

Để bảo vệ khỏi DNS-rebinding (CVE-2025-66414), server xác thực header Host (phải là mcp.foura.ai hoặc localhost) và header Origin nếu có (allowlist: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Các caller server-to-server (curl, các MCP client ở chế độ stdio bridge) không gửi Origin và được cho đi qua trực tiếp.

Tool

Cả bốn tool đều được annotate readOnlyHint: true và openWorldHint: true theo đặc tả MCP 2025-06-18. Các client tự động phê duyệt các read-only tool đáng tin cậy sẽ gọi chúng mà không cần modal xác nhận cho mỗi request.

foura_auto là tùy chọn mặc định thông minh: cung cấp cho nó một URL và nó sẽ trả về nội dung, tự động chọn phương thức fetch cho bạn. Ba tool còn lại là các primitive cấp thấp hơn mà nó điều phối, hãy sử dụng chúng khi bạn muốn kiểm soát rõ ràng.

foura_auto

Cung cấp URL cho tool khi bạn muốn FourA chọn phương thức request. Nó sẽ thực hiện các lần thử có giới hạn qua các path HTTP, proxy và trình duyệt có sẵn. Truyền validate trên các target được bảo vệ để response phải chứa nội dung xác định trang thực. Nếu không có lần thử nào đáp ứng được xác thực, tool sẽ trả về lỗi thay vì hiển thị trang challenge như là thành công.

Response bao gồm chi tiết hoàn tất trong meta và theo mặc định là một session có thể tái sử dụng kèm theo proxy, cookies và userAgent. Để thực hiện follow-up thông thường, hãy gọi foura_single với session.proxy là proxy, serialize các cookie thành header Cookie và gửi session.userAgent dưới dạng header User-Agent. Đối với render JavaScript, hãy truyền các giá trị session cho những trường foura_browser tương ứng.

foura_single

Một HTTP request, trả về response. Phản ánh POST /api/single/ theo tỷ lệ một-một.

Sử dụng cho các trang tĩnh, JSON API, HTML được server-rendered.

Chọn trình duyệt để hiển thị

Một request sẽ hiển thị Google Chrome mới nhất theo mặc định. Khi một target chấp nhận trình duyệt này và từ chối trình duyệt khác, hãy thiết lập browser (Chrome, Edge, Safari, Firefox hoặc Tor), os (Windows, macOS, Android hoặc iOS), hoặc version, hoặc truyền một id profile chính xác:

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

Phiên bản mới nhất sẽ được ưu tiên khi có nhiều profile khớp. Một kết hợp không tồn tại sẽ trả về một lỗi liệt kê các lựa chọn khả dụng, vì vậy một request sẽ không bao giờ được gửi dưới dạng trình duyệt mà bạn không chọn. Việc lựa chọn yêu cầu unblocker, tính năng này được bật theo mặc định. Danh mục được công bố tại GET /api/profiles và không yêu cầu API key.

Bốn trường tương tự nằm trong đối tượng request của foura_proxy.

foura_proxy

Định tuyến một HTTP request qua các proxy luân phiên với khả năng tự động thử lại. Sử dụng tính năng này khi foura_single bị chặn hoặc mục tiêu yêu cầu một quốc gia thoát cụ thể.

Thiết lập exitCountries thành một allowlist nghiêm ngặt gồm các mã quốc gia hai chữ cái mà mục tiêu có thể thấy, do người dùng cung cấp hoặc theo yêu cầu của mục tiêu:

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

Các giá trị được cắt bỏ khoảng trắng thừa, viết hoa, và loại bỏ trùng lặp. Các proxy có lối ra không xác định sẽ bị loại trừ, và request không bao giờ dự phòng về một quốc gia không được yêu cầu. Quá trình chọn lựa sử dụng siêu dữ liệu quốc gia hiển thị với mục tiêu mới nhất hiện có, thường được cập nhật trong vòng mười phút; đây không phải là tra cứu định vị địa lý trực tiếp trong quá trình request. Không suy luận quốc gia phục vụ từ địa chỉ host của proxy.

Một thành công theo phạm vi trả về exitCountry và ID proxy có thể tái sử dụng. Kiểm tra xem exitCountry có thuộc về allowlist đã yêu cầu hay không. Nếu pool hiện tại không có kết quả khớp, công cụ trả về code: "no_eligible_proxy" với phạm vi đã chuẩn hóa trong details.exitCountries. Giữ nguyên phạm vi đó và thử lại sau. Chỉ thay đổi hoặc mở rộng phạm vi khi người dùng thay đổi yêu cầu một cách rõ ràng.

Nếu trang được chọn sau này cần JavaScript, hãy truyền ID proxy đã trả về cho foura_browser.proxy để trình duyệt tái sử dụng cùng một lối ra.

foura_browser

Phiên trình duyệt đầy đủ. JavaScript chạy, DOM kết xuất, cookie được trả về. Phản chiếu POST /api/browser/.

Sử dụng cho các ứng dụng một trang, nội dung tải lười (lazy-loaded), hoặc các trang nằm sau thử thách chống bot cần trình duyệt thực để vượt qua.

Đối với các định dạng đầu vào, giá trị mặc định, và quy tắc xác thực trên từng công cụ, hãy tham khảo tài liệu tham khảo endpoint REST. Lược đồ công cụ khớp với API REST ở từng trường, cộng thêm tham số tùy chọn offload_large chỉ dành cho MCP (xem bên dưới).

Khi mục tiêu chạy kiểm tra bot

foura_single và foura_proxy trả về defense khi mục tiêu đã chạy kiểm tra bot trong quá trình truy cập body. defense.solved: true có nghĩa là quá trình kiểm tra đã đạt và data là trang thực sự; false có nghĩa là body có thể là một trang thử thách. Hãy thử lại với browser, os, hoặc version khác, hoặc chuyển lên sử dụng foura_proxy hoặc foura_browser, thay vì coi trang thử thách đó là nội dung.

Response định kiểu

Mỗi response công cụ bao gồm cả content (văn bản tóm tắt mà người có thể đọc) và structuredContent (JSON định kiểu được xác thực đối với outputSchema của công cụ). Mỗi công cụ có một định dạng duy nhất:

foura_auto: định dạng đơn { status, headers, data } cộng với meta ({ rung, solved, attempts, credits }, luôn hiện diện, trong đó rung là một trong các giá trị cache, probe, proxy, browser, fail) và, theo mặc định, session ({ proxy, cookies, userAgent }) để phát lại thông qua các công cụ cấp thấp hơn. Không có total_time.
foura_single: { status, headers, data, total_time, ... } (headers là một mảng, một mục cho mỗi bước nhảy redirect)
foura_proxy: giống như single cộng với { proxy, total }; một thành công theo phạm vi cũng bao gồm exitCountry
foura_browser: định dạng phân biệt { status, headers: object, body, cookies, userAgent } (lưu ý: body có thể là một chuỗi hoặc đối tượng tùy thuộc vào content-type)

Các client hỗ trợ structuredContent có thể truyền trực tiếp đối tượng đã định kiểu vào LLM thay vì yêu cầu nó phân tích cú pháp JSON từ văn bản xuôi.

Các header response đa giá trị

Các header xuất hiện nhiều lần (Set-Cookie, Link, WWW-Authenticate) được trả về dưới dạng mảng:

{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}

Điều này quan trọng đối với các trang web thiết lập các cookie phiên + theo dõi + đồng ý trong một response duy nhất (hầu hết các trang thương mại điện tử).

Các response lớn: `offload_large` (mặc định: inline)

Theo mặc định (từ bản v0.2.0), toàn bộ nội dung body của response được trả về inline trong structuredContent bất kể kích thước. Điều này hoạt động trên mọi MCP client ngay khi vừa cài đặt.

Nếu client của bạn hỗ trợ MCP resources/read VÀ bạn muốn tiết kiệm token trên các trang lớn, hãy truyền offload_large: true cho mỗi lần gọi tool. Các response >= 50 KB sau đó được ghi vào ổ đĩa, được trả về dưới dạng một resource_link và client của bạn chỉ fetch phần body khi thực sự cần. Các payload được cache sẽ hết hạn sau 1 giờ.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}

Máy khách	`offload_large: true`
Claude Desktop	chưa có, hãy để mặc định `false`
Claude Code, Cursor, Windsurf	được hỗ trợ
VS Code MCP extension	được hỗ trợ

Cách ly đối tượng thuê (Tenant-isolated): mỗi khóa API có một không gian tên riêng (sha256(apiKey)[:16]). Chỉ khóa đã lưu trữ payload mới có thể đọc lại nó. Việc đọc chéo đối tượng thuê sẽ trả về Payload not found mà không làm lộ sự tồn tại của dữ liệu.

Prompt tích hợp sẵn

Sáu mẫu luồng công việc hiển thị dưới /prompts trong bất kỳ máy khách MCP nào. Mỗi mẫu lấy các đối số được đặt tên và trả về một tin nhắn người dùng theo mẫu để điều phối một hoặc nhiều công cụ.

Prompt	Đối số	Chức năng
`smart_fetch`	`url`, tùy chọn `must_contain`, `extract`	Tự động lấy (chọn phương thức, xử lý bảo vệ bot), sau đó trả về hoặc trích xuất nội dung
`scrape_product_page`	`url`	Lấy bằng trình duyệt, sau đó trích xuất tiêu đề sản phẩm, giá cả, hình ảnh, tồn kho, SKU dưới dạng JSON
`extract_article`	`url`	Lấy đơn với proxy dự phòng, sau đó loại bỏ điều hướng/quảng cáo và trả về bài viết sạch dưới dạng JSON
`monitor_pricing`	`url`, tùy chọn `target_price`	Lấy qua proxy, trích xuất giá hiện tại, so sánh với giá mục tiêu
`check_endpoint_health`	`url`, tùy chọn `expected_text`	Lấy đơn với xác thực nghiêm ngặt, trả về khả năng tiếp cận và thời gian
`bulk_fetch_urls`	`urls` (phân tách bằng dấu phẩy)	Lấy đơn song song, tự động dự phòng sang proxy cho mỗi URL, chỉ trả về siêu dữ liệu

Các prompt tiêu tốn không token khi nhàn rỗi. Chỉ các prompt được gọi mới đi vào ngữ cảnh LLM.

Văn bản đầy đủ cộng với các prompt dự phòng thủ công: MCP Recipes.

Error envelope

Mọi lỗi (isError: true) đều mang một envelope structuredContent. Các trường tối thiểu trên mọi lỗi:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

Đối với các lỗi upstream có trạng thái HTTP, status cũng sẽ hiển thị. Đối với các lỗi giới hạn lưu lượng và dung lượng, envelope upstream bổ sung thêm retryAfter, current.{concurrency, rpm} và limits.{maxConcurrency, maxRpm}. Xem Lỗi API để biết chi tiết về định dạng REST bên dưới.

Các giá trị code ổn định:

Mã	HTTP	Ý nghĩa	Có an toàn khi thử lại?
`ssrf_blocked`	n/a	IP đích nằm trong dải mạng riêng hoặc được bảo lưu (RFC 5735, 6598, IPv6 dành riêng)	Không, đổi URL
`upstream_non_json`	khác nhau	Upstream trả về phần thân có định dạng sai	Có thể, cần điều tra
`output_validation_failed`	n/a	`outputSchema` của máy chủ MCP đã từ chối phản hồi upstream (lỗi máy chủ hoặc định dạng upstream không mong muốn)	Có thể, hãy báo cáo
`bad_request`	400	Định dạng đầu vào bị từ chối	Không, sửa đổi đối số
`auth_failed`	401	Khóa bị thiếu, không hợp lệ hoặc đã bị vô hiệu hóa	Không, sửa khóa
`forbidden`	403	Đã xác thực nhưng không được phép	Không, hoặc chuyển sang `foura_proxy`
`not_found`	404	Đích hoặc endpoint bị thiếu	Không
`rate_limited`	429	Đạt giới hạn RPM	Có, đợi `retryAfter`
`at_capacity`	503	Đạt giới hạn đồng thời	Có, đợi `retryAfter`
`service_disabled`	503	Đang trong thời gian bảo trì hoặc gói của bạn không bao gồm công cụ này	Liên hệ bộ phận hỗ trợ
`service_unavailable`	503	Lỗi 503 chung	Có, thời gian backoff ngắn
`upstream_error`	500+	Lỗi 5xx từ Upstream	Có, exponential backoff
`upstream_client_error`	4xx	Các lỗi 4xx khác	Thường là không
`upstream_unknown`	khác	Phòng vệ, không nên xảy ra trên thực tế	Cần điều tra
`no_eligible_proxy`	n/a	Không có proxy nào khớp với phạm vi `exitCountries` nghiêm ngặt	Thử lại sau; chỉ thay đổi phạm vi một cách rõ ràng

Các agent LLM có thể đọc trực tiếp code để thực hiện logic thử lại mà không cần phân tích cú pháp dạng văn bản. Hướng dẫn xác thực: Xác thực.

Giới hạn

Mặc định sử dụng phần thân nội tuyến. Với offload_large: true, các phản hồi >= 50 KB sẽ được lưu vào đĩa + resource_link (mỗi người dùng, TTL 1 giờ).
Các đích đến riêng tư bị từ chối (RFC 5735, RFC 6598, dải IPv6 dành riêng) ở tầng MCP. Chỉ các host công khai mới được chuyển tiếp.
Giới hạn phần thân của request là 256 KB đối với các request /mcp gửi đến (payload MCP thực tế < 4 KB).
Rate limits được FourA API thực thi cho từng dịch vụ. Xem Giới hạn lưu lượng.

Tự lưu trữ (Self-Hosting)

Toàn bộ mã nguồn máy chủ được công khai trên GitHub theo giấy phép @fouradata/mcp. Clone kho lưu trữ, chạy npm install, npm run build và chạy node dist/http.js để khởi tạo instance của riêng bạn. Hoạt động ở chế độ phi trạng thái trong một container duy nhất phía sau bất kỳ bộ cân bằng tải nào.

Cấu hình môi trường:

Biến	Mặc định	Mục đích
`PORT`	`3076`	Cổng lắng nghe HTTP
`FOURA_API_BASE`	`https://api.foura.ai/api`	Base URL của upstream FourA REST
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Nơi các response >= 50 KB được cache trên ổ đĩa (với `offload_large: true`)
`FOURA_MCP_ALLOWED_HOSTS`	`mcp.foura.ai,localhost,127.0.0.1,[::1]`	Danh sách cho phép hostname cho header `Host` (phòng thủ DNS-rebinding)
`FOURA_MCP_ALLOWED_ORIGINS`	`https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com`	Danh sách cho phép origin cho các caller từ trình duyệt
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	URL được trả về trong `WWW-Authenticate` khi có lỗi 401

Container chính thức chạy dưới quyền uid 1001 (không phải root). Host bind mount /data/payloads phải cho phép ghi bởi uid đó.

Mở rộng theo chiều ngang phía sau bất kỳ load balancer nào. Client cung cấp khóa của họ trên mỗi request, do đó không có sticky session.

Cập nhật: 6 tháng 8, 2026

MCP Server

MCP Server

Bắt đầu nhanh: stdio cục bộ (được đề xuất cho Claude Desktop)

Bắt đầu nhanh: hosted (Streamable HTTP)

Tham chiếu endpoint được lưu trữ

Tool

foura_auto

foura_single

Chọn trình duyệt để hiển thị

foura_proxy

foura_browser

Khi mục tiêu chạy kiểm tra bot

Response định kiểu

Các header response đa giá trị

Các response lớn: offload_large (mặc định: inline)

Prompt tích hợp sẵn

Error envelope

Giới hạn

Tự lưu trữ (Self-Hosting)

Các response lớn: `offload_large` (mặc định: inline)