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 ba công cụ tích hợp sẵn và năm prompt quy trình công việc. Không cần mã tích hợp, không cần HTTP client tùy chỉnh.

Khởi động nhanh: stdio cục bộ (khuyến nghị cho Claude Desktop)

Lấy một key tại foura.ai/dashboard#api-keys (một lần nhấp, chỉ hiển thị một lần khi tạo, định dạng pk_live_...). Thêm cấu hình 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 ý quan trọng cho Claude Desktop: thoát hoàn toàn Claude Desktop (Cmd+Q trên macOS) trước khi chỉnh sửa file 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 tải xuống @fouradata/mcp trong lần khởi chạy đầu tiên (~10 giây) và chạy nó như một tiến trình con (subprocess) của client MCP của bạn. Không cần cài đặt toàn cục.

Client	Nơi lưu trữ 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` (thiết lập `FOURA_API_KEY` trong môi trường trước)
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code (tiện ích mở rộng MCP)	`.vscode/mcp.json`

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

Khởi động nhanh: hosted (Streamable HTTP)

Đối với các client hỗ trợ transport Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code với --transport http), hãy trỏ chúng đến endpoint hosted 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_..."
      }
    }
  }
}

Các bản dựng Claude Desktop hiện tại từ chối định dạng url thuần túy. Hãy sử dụng cấu hình stdio ở trên cho Claude Desktop, hoặc kết nối bắc cầu qua mcp-remote:

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

Tài liệu tham khảo endpoint hosted

Thuộc tính	Giá trị
URL	`https://mcp.foura.ai/mcp`
Transport	Streamable HTTP (POST `/mcp`, SSE responses)
Authentication	`Authorization: Bearer pk_live_...` trên 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`)
Thử thách 401	`WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

Server hosted là stateless. Mỗi request đều mang theo key riêng, server sẽ chuyển tiếp key này đến FourA API dưới dạng X-API-Key. Một key có thể mở cả ba công cụ.

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

Công cụ

Cả ba công cụ đều được chú thích readOnlyHint: true và openWorldHint: true theo đặc tả MCP 2025-06-18. Các client tự động phê duyệt các công cụ chỉ đọc đáng tin cậy sẽ gọi chúng mà không cần hộp thoại xác nhận cho mỗi request.

foura_single

Một HTTP request, nhận lại response. 200ms đến 2s. Khớp một-đối-một với POST /api/single/.

Sử dụng cho các trang tĩnh, JSON API, HTML được render phía server.

foura_proxy

HTTP request được định tuyến qua một proxy pool xoay vòng với tính năng tự động thử lại. 1 đến 5s. Khớp với POST /api/proxy/.

Sử dụng khi foura_single trả về 403, CAPTCHA, hoặc nội dung bị chặn địa lý. Response bao gồm ID proxy đã thành công (proxy) và tổng thời gian thực tế tính bằng giây (total, float).

foura_browser

Phiên trình duyệt đầy đủ. JavaScript chạy, DOM được render, cookie được trả về. 2 đến 10s. Khớp với POST /api/browser/.

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

Để biết cấu trúc đầu vào, giá trị mặc định và quy tắc xác thực của từng công cụ, hãy tham khảo tài liệu tham khảo REST endpoint. Schema của công cụ khớp từng trường một với REST API, cộng thêm tùy chọn offload_large chỉ dành cho MCP (xem bên dưới).

Response có kiểu dữ liệu

Mỗi response của công cụ đều bao gồm cả content (bản tóm tắt văn bản dễ đọc) và structuredContent (JSON có kiểu dữ liệu được xác thực theo outputSchema của công cụ). Mỗi công cụ có cấu trúc độc nhất riêng:

foura_single: { status, headers, data, total_time, ... } (headers là một mảng, mỗi phần tử tương ứng với một bước chuyển hướng - redirect hop)
foura_proxy: giống như single cộng thêm { proxy, total } (trong đó total là số giây dạng float, tổng thời gian bên ngoài bao gồm cả các lần thử lại)
foura_browser: cấu trúc riêng biệt { status, headers: object, body, cookies, userAgent } (lưu ý: body có thể là string hoặc object tùy thuộc vào content-type)

Các client hỗ trợ structuredContent (Claude Desktop, Cursor, Windsurf tính đến năm 2026) sẽ chuyển trực tiếp object có kiểu dữ liệu này tới LLM, bỏ qua bước chuyển đổi JSON-thành-string để re-tokenization. Dự kiến tiết kiệm 30-40% token trên các response thông thường.

Header response có nhiều giá trị

Các header xuất hiện nhiều lần (Set-Cookie, Link, WWW-Authenticate) sẽ đượ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 rất quan trọng đối với các trang web thiết lập cookie phiên + theo dõi + chấp thuận trong cùng một response (hầu hết các trang thương mại điện tử).

Response lớn: `offload_large` (mặc định: inline)

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

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ượt gọi công cụ. Các response ≥ 50 KB sau đó sẽ được ghi vào đĩa, trả về dưới dạng một resource_link, và client của bạn chỉ tải body khi thực sự cần thiết. 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
}

Client	`offload_large: true`
Claude Desktop	chưa hỗ trợ, hãy để mặc định là `false`
Claude Code, Cursor, Windsurf	được hỗ trợ
Tiện ích mở rộng VS Code MCP	được hỗ trợ

Cô lập theo tenant (Tenant-isolated): mỗi API key nhận được namespace riêng (sha256(apiKey)[:16]). Chỉ key đã lưu trữ payload mới có thể đọc lại payload đó. Việc đọc chéo giữa các tenant sẽ trả về Payload not found mà không làm rò rỉ thông tin tồn tại của dữ liệu.

Prompt tích hợp sẵn

Năm template quy trình công việc xuất hiện dưới mục /prompts trong bất kỳ client MCP nào. Mỗi template nhận các đối số có tên và trả về một tin nhắn người dùng dạng template để điều phối một hoặc nhiều công cụ.

Prompt	Đối số	Chức năng
`scrape_product_page`	`url`	Tải bằng trình duyệt, sau đó trích xuất tiêu đề sản phẩm, giá cả, hình ảnh, kho hàng, SKU dưới dạng JSON
`extract_article`	`url`	Gọi single với fallback sang proxy, sau đó loại bỏ thanh điều hướng/quảng cáo và trả về JSON bài viết sạch
`monitor_pricing`	`url`, tùy chọn `target_price`	Tải bằng 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`	Gọi single với xác thực nghiêm ngặt, trả về khả năng tiếp cận và thời gian phản hồi
`bulk_fetch_urls`	`urls` (phân tách bằng dấu phẩy)	Gọi single song song, tự động fallback sang proxy cho mỗi URL, chỉ trả về metadata

Các prompt không tốn token khi ở trạng thái rảnh. Chỉ các prompt được gọi mới được đưa vào ngữ cảnh LLM.

Toàn bộ văn bản cùng các prompt fallback thủ công: MCP Recipes.

Cấu trúc lỗi

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

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

Đối với các lỗi upstream có mã trạng thái HTTP, trường status cũng sẽ xuất hiện. Đối với các lỗi rate limit và dung lượng (capacity), cấu trúc upstream sẽ bổ sung thêm retryAfter, current.{concurrency, rpm}, và limits.{maxConcurrency, maxRpm}. Xem API Errors để biết cấu trúc REST cơ bản.

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

| Code | HTTP | Ý nghĩa | Thử lại an toàn? | |---|---| | ssrf_blocked | n/a | IP mục tiêu nằm trong dải IP riêng tư hoặc được bảo lưu (RFC 5735, 6598, IPv6 được bảo lưu) | Không, hãy thay đổi URL | | upstream_non_json | thay đổi | Upstream trả về body sai định dạng | Có thể, hãy kiểm tra | | output_validation_failed | n/a | outputSchema của MCP server đã từ chối response từ upstream (lỗi server hoặc cấu trúc upstream không mong muốn) | Có thể, hãy báo cáo | | bad_request | 400 | Cấu trúc đầu vào bị từ chối | Không, hãy sửa lại các đối số | | auth_failed | 401 | Key bị thiếu, không hợp lệ hoặc đã bị vô hiệu hóa | Không, hãy sửa lại key | | 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 | Không tìm thấy mục tiêu hoặc endpoint | Không | | rate_limited | 429 | Đạt giới hạn RPM | Có, hãy đợi retryAfter | | at_capacity | 503 | Đạt giới hạn concurrency (đồng thời) | Có, hãy đợi retryAfter | | service_disabled | 503 | Thời gian bảo trì hoặc gói dịch vụ 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ực hiện backoff ngắn | | upstream_error | 500+ | Lỗi 5xx từ upstream | Có, thực hiện exponential backoff | | upstream_client_error | 4xx | Lỗi 4xx khác | Thường là không | | upstream_unknown | khác | Phòng thủ, thực tế không xảy ra | Kiểm tra |

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

Giới hạn

Body dạng inline theo mặc định. Với offload_large: true, các response ≥ 50 KB sẽ được lưu vào đĩa + resource_link (theo từng tenant, TTL 1 giờ).
Các mục tiêu riêng tư bị từ chối (RFC 5735, RFC 6598, các khối IPv6 được bảo lưu) ở lớp MCP. Chỉ các host công khai mới được chuyển tiếp.
Giới hạn body request là 256 KB đối với các request /mcp đi vào (payload MCP thực tế < 4 KB).
Các rate limit được áp dụng bởi FourA API cho mỗi dịch vụ. Xem Rate Limits.

Tự chạy trên máy chủ riêng (Self-Hosting)

Mỗi instance chạy trong một container theo dạng stateless. Bản mirror GitHub công khai sẽ ra mắt cùng phiên bản v1.0. Cho đến lúc đó, mã nguồn nằm trong một repo riêng tư và container image sẽ được cung cấp theo yêu cầu. Liên hệ support@foura.ai để được trải nghiệm sớm.

Môi trường có thể cấu hình:

Biến	Mặc định	Mục đích
`PORT`	`3076`	Cổng lắng nghe HTTP
`FOURA_API_BASE`	`https://api.foura.ai/api`	URL cơ sở REST của FourA upstream
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	Nơi các response ≥ 50 KB được cache trên đĩa (khi bật `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` (bảo vệ chống 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 trình duyệt
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	URL được trả về trong `WWW-Authenticate` khi gặp lỗi 401

Chạy dưới dạng uid 1001 (non-root) trong container chính thức. Thư mục bind mount của host /data/payloads phải có quyền ghi cho uid đó.

Mở rộng quy mô theo chiều ngang phía sau bất kỳ bộ cân bằng tải (load balancer) nào. Các client cung cấp key của họ trên mỗi request, vì vậy không cần sticky session.

Cập nhật: 1 tháng 7, 2026

MCP Server

MCP Server

Khởi động nhanh: stdio cục bộ (khuyến nghị cho Claude Desktop)

Khởi động nhanh: hosted (Streamable HTTP)

Tài liệu tham khảo endpoint hosted

Công cụ

foura_single

foura_proxy

foura_browser

Response có kiểu dữ liệu

Header response có nhiều giá trị

Response lớn: offload_large (mặc định: inline)

Prompt tích hợp sẵn

Cấu trúc lỗi

Giới hạn

Tự chạy trên máy chủ riêng (Self-Hosting)

Response lớn: `offload_large` (mặc định: inline)