# MCP Server

> URL: https://foura.ai/vi/docs/mcp/server
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Sử dụng FourA từ bất kỳ client [Model Context Protocol](https://modelcontextprotocol.io) nào (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) dưới dạng bốn tool gốc và sáu workflow prompt. Không cần viết code tích hợp, không cần HTTP client tùy chỉnh.

Mã nguồn mở trên [GitHub](https://github.com/fouradata/mcp); có trên [npm](https://www.npmjs.com/package/@fouradata/mcp) dưới tên `@fouradata/mcp`. Bản phát hành hiện tại: `0.8.3`.

## Bắt đầu nhanh: stdio cục bộ (khuyên dùng cho Claude Desktop)

Lấy API key tại [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) (chỉ một lần nhấp, định dạng `pk_live_...`, và chọn **Reveal** để xem lại key sau này). Thêm cấu hình sau vào client MCP của bạn:

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

> **Lưu ý quan trọng cho 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 tiến trình con của MCP client. Không cần cài đặt global.

| 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`, nằm dưới khóa cấp cao nhất `servers` thay vì `mcpServers` |

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ợ giao thức truyền tải Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code với `--transport http`), hãy trỏ chúng đến endpoint được lưu trữ thay vì chạy một tiến trình con cục bộ:

```json
{
  "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 làm cầu nối (bridge) hosted endpoint thông qua `mcp-remote`:

```json
{
  "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 hosted endpoint

| Thuộc tính | Giá trị |
|---|---|
| URL | `https://mcp.foura.ai/mcp` |
| Giao vận | Streamable HTTP (POST `/mcp`, SSE response) |
| Xác thực | `Authorization: Bearer pk_live_...` trên mỗi request. Key trần trong `Authorization`, hoặc `X-API-Key: pk_live_...`, cũng hoạt động |
| 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"` |

Thử thách 401 không chứa tham số RFC 9728 `resource_metadata`, có chủ đích. Việc công bố tham số này khiến client hỗ trợ OAuth bắt đầu một luồng mà server này không triển khai. Hãy gửi key `pk_live_` của bạn dưới dạng Bearer token và lỗi 401 sẽ biến mất.

Hosted server ở trạng thái stateless. Mỗi request mang theo key riêng, sau đó server sẽ chuyển tiếp đến FourA API dưới dạng `X-API-Key`. Một key mở khóa cho toàn bộ bốn công cụ.

Để bảo vệ chống lạ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` khi có mặt (allowlist: `mcp.foura.ai`, `claude.ai`, `app.cursor.sh`, `app.cursor.com`). Các caller server-to-server (`curl`, MCP client ở chế độ stdio bridge) không gửi `Origin` và được thông qua trực tiếp.

## Công cụ

Cả bốn công cụ đều được chú thích `readOnlyHint: true` và `openWorldHint: true` theo [đặc tả MCP 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/server/tools). 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 modal xác nhận cho mỗi request.

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

### foura_auto

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

Response bao gồm chi tiết hoàn thành trong `meta` và theo mặc định là một `session` có thể tái sử dụng kèm `proxy`, `cookies` và `userAgent`. Đối với lượt gọi tiếp theo thông thường, gọi `foura_single` với `session.proxy` làm `proxy`, tuần tự hóa cookie thành header `Cookie` và gửi `session.userAgent` làm header `User-Agent`. Đối với render JavaScript, truyền các giá trị session vào các trường `foura_browser` tương ứng.

Đặt `exitClass: "premium"` để cho phép Auto tự động chuyển lên exit cao cấp khi pool tiêu chuẩn không thể truy cập trang. `exitClass: "standard"` và việc bỏ qua trường này đều giữ Auto ở pool tiêu chuẩn, và chỉ request nào chỉ định một class mới nhận lại `exitClass`. Cơ chế hoạt động tương tự như trên `foura_proxy`: đây là mức cho phép chứ không phải lệnh bắt buộc, được tính vào lưu lượng premium trong gói của bạn, và bị từ chối với `code: "plan_limit_premium"` nếu gói không có exit cao cấp. Giá trị `exitClass` của kết quả cho biết class nào đã phản hồi. Xem [exitClass trên Smart Fetch](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

### foura_single

Một HTTP request, nhận lại response. Tương ứng một-một với [`POST /api/single/`](https://foura.ai/docs/api/endpoints).

Sử dụng cho các trang tĩnh, JSON API, HTML render từ server.

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

Theo mặc định, một request sẽ hiển thị dưới dạng Google Chrome mới nhất. Khi mục tiêu chấp nhận một trình duyệt này nhưng từ chối trình duyệt khác, hãy đặt `browser` (Chrome, Edge, Safari, Firefox hoặc Tor), `os` (Windows, macOS, Android hoặc iOS), hoặc `version`, hoặc truyền chính xác một `profile` id:

```json
{
  "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 tổ hợp không tồn tại sẽ trả về lỗi liệt kê các tùy chọn khả dụng, do đó request không bao giờ bị gửi đi dưới dạng một trình duyệt mà bạn không chọn. Việc lựa chọn yêu cầu `unblocker`, vốn được bật theo mặc định. Danh mục được công bố tại [`GET /api/profiles`](https://foura.ai/docs/api/endpoints) và không cần API key.

Bốn trường tương tự nằm bên 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 có tự động thử lại. Sử dụng tính năng này khi `foura_single` bị chặn hoặc đích đến yêu cầu một quốc gia gửi đi cụ thể.

Đặt `exitCountries` thành một allowlist nghiêm ngặt gồm các mã quốc gia hai chữ cái mà phía đích thấy được, do người dùng cung cấp hoặc theo yêu cầu của đích đến:

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

Các giá trị được cắt tỉa khoảng trắng, chuyển thành chữ hoa và loại bỏ trùng lặp. Các cổng exit thuộc standard pool không xác định được quốc gia sẽ bị loại trừ, và standard pool không bao giờ tự ý chuyển hướng về một quốc gia ngoài yêu cầu. Một premium exit cũng được giới hạn trong danh sách này: với `exitClass: "premium"`, standard pool vẫn được ưu tiên trước, và premium exit sẽ xuất phát từ một trong các quốc gia bạn đã chọn rồi định danh quốc gia đó trong `exitCountry`. Việc lựa chọn dựa trên 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à quá trình tra cứu geolocation theo thời gian thực trong khi gửi request. Không suy đoán quốc gia phục vụ từ địa chỉ host của proxy.

Một kết quả thành công theo phạm vi sẽ trả về `exitCountry` và ID `proxy` có thể tái sử dụng. Hãy kiểm tra để đảm bảo `exitCountry` thuộc allowlist đã yêu cầu. Nếu pool hiện tại không có kết quả phù hợp, công cụ sẽ trả về `code: "no_eligible_proxy"` kèm theo phạm vi đã chuẩn hóa trong `details.exitCountries`. Hãy 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 chủ động thay đổi yêu cầu. Phân phạm vi quốc gia được bao gồm từ gói Startup trở lên. Với gói không hỗ trợ, lệnh gọi gửi kèm `exitCountries` sẽ bị từ chối với `403` và `X-FourA-Limit: plan_limit_feature`.

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

Đặt `exitClass: "premium"` cho mục tiêu mà standard pool không thể truy cập dù đã thử bao nhiêu exit đi nữa. Đây là một sự cho phép, không phải mệnh lệnh bắt buộc: standard pool vẫn sẽ cạnh tranh để lấy phản hồi và thường thành công trước, và request được phản hồi trước khi bất kỳ premium exit nào được thử sẽ không tốn lưu lượng premium. Một lượt thử premium sẽ tính lưu lượng đã sử dụng ngay cả khi thất bại. Phản hồi sẽ trả về `exitClass`, là `premium` hoặc `standard`, để bạn có thể theo dõi trên từng request xem class nào đã phục vụ. `standard` cũng là kết quả trả về khi lưu lượng premium trong gói của bạn đã hết, và đây là một kết quả bình thường chứ không phải lỗi. `exitClass: "standard"` nghiêm cấm hoàn toàn việc nâng cấp lên premium. `exitClass: "premium"` trên gói không có premium exit sẽ bị từ chối với `code: "plan_limit_premium"`. Xem thêm tại [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

Khi quá trình luân chuyển phải chuyển sang trình duyệt khác để nhận phản hồi, một response thành công sẽ mang theo `profile`: id hồ sơ trong catalog mà hệ thống đã chọn định hình. Hãy truyền giá trị này dưới dạng `profile` ở lệnh gọi tiếp theo để sử dụng cùng một trình duyệt.

Một lượt luân chuyển thất bại sẽ mang theo `attemptReport` bên cạnh thông báo lỗi: một câu `summary`, kèm theo số lượng phân loại các exit không bao giờ phản hồi (`noResponse`), các exit bị bot check từ chối (`defense`, với các nhà cung cấp trong `vendors`), các trang đã tải về nhưng chỉ bị từ chối bởi chính `validate.data` của bạn (`contentRejected`), `statusRejected`, và `other`. `profilesTried` liệt kê các trình duyệt mà tác vụ đã gửi đi, theo thứ tự sử dụng đầu tiên, với `default` có nghĩa là request đã được gửi đi chính xác như văn bản gốc. Giá trị `contentRejected` cao nghĩa là FourA đã gửi về trang thật nhưng quy tắc của chính bạn đã loại bỏ chúng. Xem [Why a Proxy Request Ran Out of Tries](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### foura_browser

Phiên browser đầy đủ. JavaScript thực thi, DOM kết xuất, cookie được trả về. Tương đồng với [`POST /api/browser/`](https://foura.ai/docs/api/endpoints).

Sử dụng cho single-page app, nội dung lazy-load, hoặc các trang có quy trình kiểm tra cần một browser thực sự để hoàn tất.

Để biết cấu trúc input, giá trị mặc định và quy tắc xác thực cho từng công cụ, hãy tham khảo [tài liệu tham khảo REST endpoint](https://foura.ai/docs/api/endpoints). Schema của công cụ khớp với REST API, cộng thêm tuỳ chọn kích hoạt `offload_large` chỉ dành cho MCP (xem bên dưới), ngoại trừ hai trường hợp: `foura_browser` không có trường `lean`, và `foura_proxy` chưa có các trường [exit location](https://foura.ai/docs/api/endpoints#exit-location). Giá trị được gửi dưới các tên này sẽ không bao giờ đến được API. Để thiết lập, hãy gọi trực tiếp [`POST /api/browser/`](https://foura.ai/docs/api/endpoints) hoặc [`POST /api/proxy/`](https://foura.ai/docs/api/endpoints).

### Khi mục tiêu kích hoạt bot check

`foura_single` và `foura_proxy` trả về `defense` khi mục tiêu kích hoạt bot check trước khi trả về body. `defense.solved: true` nghĩa là đã vượt qua kiểm tra và `data` là trang thực tế; `false` nghĩa là body có thể là trang challenge. Hãy thử lại với browser, os hoặc phiên bản khác, hoặc chuyển lên `foura_proxy` hay `foura_browser`, thay vì xử lý trang challenge như nội dung thông thường.

## Phản hồi có định kiểu

Mỗi phản hồi 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ó định kiểu được xác thực theo `outputSchema` của công cụ). Mỗi công cụ có cấu trúc riêng biệt:

- `foura_auto`: cấu trúc single `{ status, headers, data }` kèm theo `meta` (`{ rung, solved, attempts, credits, attemptsByEngine, browserRequests }`, luôn có mặt, trong đó `rung` là một trong các giá trị `cache`, `probe`, `proxy`, `browser`, `warmup`, `fail`) và theo mặc định là `session` (`{ proxy, cookies, userAgent }`) để gửi lại qua các công cụ cấp thấp hơn; một request có chỉ định class cũng bao gồm `exitClass`. `meta.attemptsByEngine` đếm số lượng request mà lệnh gọi đã gửi tới Single, Proxy và Browser, còn `meta.browserRequests` đếm những request đã sử dụng hạn mức Browser hàng ngày của bạn. Khi thất bại cũng sẽ bao gồm `attemptReport`. Không có `total_time`.
- `foura_single`: `{ status, headers, data, total_time, ... }` (headers là một mảng, mỗi mục ứng với một chặng redirect)
- `foura_proxy`: tương tự như single kèm theo `{ proxy, total }`; một phản hồi thành công theo scope cũng bao gồm `exitCountry`, một request có chỉ định class bao gồm `exitClass`, một lần luân phiên thay đổi nhóm browser bao gồm `profile`, và khi thất bại bao gồm `attemptReport`
- `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 tuỳ theo content-type)

Mỗi công cụ cũng báo cáo chi phí của lệnh gọi và cách truy vết lệnh gọi đó, được đọc từ response header của API:

- `credits`: số credit mà lệnh gọi này đã tiêu tốn. Trường này cũng xuất hiện khi thất bại, vì tác vụ vẫn được thực thi. Bạn chỉ bị tính phí cho lệnh gọi thành công, do đó lệnh gọi thất bại vẫn hiển thị số credit tại đây nhưng không tốn chi phí.
- `request_id`: ID của FourA cho lệnh gọi. Hãy trích dẫn ID này khi gửi yêu cầu hỗ trợ.
- `exitClass`: `premium` khi lệnh gọi được xử lý qua premium exit. Trên `foura_single` và `foura_browser`, điều này xảy ra khi `proxy` phát lại một premium exit mà `foura_proxy` hoặc `foura_auto` tìm thấy.

Mỗi trường sẽ không xuất hiện nếu API không trả về dữ liệu, giúp client viết cho phiên bản cũ hơn tiếp tục hoạt động mà không cần thay đổi. Các giá trị tương tự được ghi chép tại [Response Headers](https://foura.ai/docs/api/response-headers).

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

### Response header đ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:

```json
{
  "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 cookie session + tracking + consent trong một response (phần lớn các trang thương mại điện tử).

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

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

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 tool call. Các response >= 50 KB sau đó sẽ được ghi vào đĩa, trả về dưới dạng `resource_link`, và client của bạn chỉ fetch body khi thực sự cần. Trên hosted server, các payload được lưu trong cache sẽ hết hạn sau 1 giờ. Trên instance riêng của bạn, không có gì tự động xóa các payload đã lưu: hãy tự dọn dẹp các tệp cũ hơn một giờ khỏi thư mục payload.

Kết quả được offload chứa `offloaded_resource_uri` và `size_bytes` thay cho body. Kết quả được offload cũng bỏ qua `defense`, và `profile` trên `foura_proxy`, vì vậy hãy bỏ qua `offload_large` trong lệnh gọi đọc các trường đó.

```json
{
  "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 giữ nguyên `false` mặc định |
| Claude Code, Cursor, Windsurf | được hỗ trợ |
| VS Code MCP extension | được hỗ trợ |

Cô lập theo tenant: mỗi API key có một namespace riêng (`sha256(apiKey)[:16]`). Chỉ key đã lưu trữ payload mới có thể đọc lại payload đó. Các thao tác đọc chéo tenant sẽ trả về `Payload not found` và không làm rò rỉ trạng thái tồn tại.

## Built-in Prompts

Sáu template quy trình làm việc hiển thị dưới `/prompts` trong bất kỳ MCP client nào. Mỗi template nhận các đối số có tên và trả về một user message dạng template để đ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 fetch (tự chọn phương thức, xử lý chống bot), sau đó trả về hoặc trích xuất nội dung |
| `scrape_product_page` | `url` | Fetch qua trình duyệt, sau đó trích xuất tiêu đề sản phẩm, giá, hình ảnh, tình trạng kho, SKU dưới dạng JSON |
| `extract_article` | `url` | Single fetch với proxy dự phòng, sau đó loại bỏ menu đ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` | Fetch 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` | Single fetch với quy trình xác thực nghiêm ngặt, trả về khả năng truy cập và thời gian phản hồi |
| `bulk_fetch_urls` | `urls` (phân tách bằng dấu phẩy) | Single fetch song song, tự động chuyển sang proxy cho từng URL, chỉ trả về metadata |

Các prompt không tiêu tốn token khi ở trạng thái chờ. Chỉ những prompt được gọi mới được đưa vào context của LLM.

Xem toàn bộ văn bản và các prompt dự phòng thủ công tại: [MCP Recipes](https://foura.ai/docs/mcp/recipes).

## Cấu trúc bao đóng lỗi

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

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

Với các lỗi upstream có HTTP status, `status` cũng sẽ xuất hiện. Với các lỗi rate limit và dung lượng, envelope upstream sẽ bổ sung `retryAfter`, `current.{concurrency, rpm}` và `limits.{maxConcurrency, maxRpm}`. Xem [API Errors](https://foura.ai/docs/api/errors) để biết cấu trúc REST cơ bản.

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

| Mã | HTTP | Ý nghĩa | Có thể thử lại an toàn? |
|---|---|---|---|
| `ssrf_blocked` | k/d | Mục tiêu là địa chỉ private hoặc reserved (RFC 5735, 6598, IPv6 reserved), URL không phải http(s), hoặc hostname không phân giải được | Không, hãy kiểm tra URL. Quá trình tra cứu tạm thời thất bại có thể được thử lại |
| `upstream_non_json` | thay đổi | Upstream trả về body sai định dạng | Có thể, hãy kiểm tra nguyên nhân |
| `output_validation_failed` | k/d | `outputSchema` của MCP server từ chối response từ upstream, hoặc tool không thể hoàn tất lệnh gọi (chưa cấu hình API key, không kết nối được API) | Có thể: kiểm tra cấu hình, sau đó báo cáo |
| `bad_request` | 400 | Cấu trúc đầu vào bị từ chối, URL mục tiêu trỏ về API riêng của FourA thay vì một trang web (chỉ có thể fetch `/inspect` tại đây), hoặc URL chứa khoảng trắng chưa được encode (hãy encode thành `%20`) | Không, hãy sửa 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 key |
| `forbidden` | 403 | Mục tiêu trả lời 403 và `validate` của bạn đã từ chối nó (kiểm tra trang web, giới hạn quốc gia) | Không, hoặc chuyển sang `foura_proxy` |
| `not_found` | 404 | Thiếu mục tiêu hoặc endpoint | Không |
| `rate_limited` | 429 | Vượt giới hạn RPM | Có, hãy đợi `retryAfter` |
| `at_capacity` | 503 | Vượt giới hạn concurrency, hoặc dịch vụ tạm tắt để bảo trì (`error` hiển thị `Service disabled`) | Có, hãy đợi `retryAfter` |
| `service_disabled` | 503 | Đã dành riêng. Dịch vụ tạm tắt để bảo trì hiện trả về `at_capacity`, và tool không có trong gói của bạn sẽ trả về `plan_limit_feature` | Liên hệ hỗ trợ |
| `service_unavailable` | 503 | Lỗi 503 chung | Có, backoff ngắn |
| `upstream_error` | 500+ hoặc 0 | Mục tiêu phản hồi bằng lỗi server, hoặc trên `foura_proxy`, `foura_browser` và `foura_auto` không bao giờ phản hồi | Có, exponential backoff |
| `upstream_client_error` | 4xx | Lỗi 4xx khác | Thường là không |
| `upstream_unknown` | khác | Request đã chạy nhưng không tạo ra phản hồi được chấp nhận: trên `foura_single` mục tiêu không phản hồi (timeout, từ chối kết nối), và trên mọi tool `validate` của bạn từ chối response 2xx hoặc 3xx. Đọc `status` và `error` | Điều tra nguyên nhân |
| `no_eligible_proxy` | k/d | Không có proxy nào khớp với phạm vi nghiêm ngặt của `exitCountries` | Thử lại sau; chỉ thay đổi phạm vi một cách rõ ràng |
| `plan_limit_*` | 403 hoặc 429 | Một trong các giới hạn gói dịch vụ của bạn đã từ chối lệnh gọi: `plan_limit_` theo sau là `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits` hoặc `bandwidth`. Xem [MCP Server Errors](https://foura.ai/docs/mcp/errors) | Đợi `retryAfter` khi có; nếu không hãy đợi đến khi giới hạn được đặt lại hoặc gói dịch vụ thay đổi |

Các LLM agent có thể đọc `code` trực tiếp cho logic thử lại (retry) mà không cần phân tích văn bản tự nhiên. Hướng dẫn xác thực: [Authentication](https://foura.ai/docs/getting-started/authentication).

## Giới hạn

- Mặc định trả về body trực tiếp (inline). 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 nội bộ bị từ chối (RFC 5735, RFC 6598, các dải IPv6 dành riêng) ở tầng MCP. Chỉ chuyển tiếp các public host.
- Giới hạn request body ở mức 256 KB đối với các request `/mcp` gửi đến (payload MCP thực tế < 4 KB).
- Rate limit do FourA API thực thi cho từng dịch vụ. Xem [Rate Limits](https://foura.ai/docs/api/rate-limits).

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

Toàn bộ mã nguồn máy chủ được công khai trên [GitHub](https://github.com/fouradata/mcp) theo `@fouradata/mcp`. Clone repo, `npm install`, `npm run build`, và chạy `node dist/http.js` để thiết lập instance của riêng bạn. Chạy stateless trong một container duy nhất phía sau bất kỳ load balancer nào.

Môi trường có thể định 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 gốc upstream FourA REST |
| `FOURA_MCP_PAYLOADS_DIR` | một thư mục `foura-mcp-payloads` trong thư mục tạm của hệ thống (tệp Docker Compose đi kèm đặt `/data/payloads`) | Nơi lưu response >= 50 KB vào bộ nhớ đệm 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 vệ 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 đối với các trình gọi từ trình duyệt |

Container chính thức chạy dưới `uid 1001` (non-root). Tệp Docker Compose đi kèm giữ `/data/payloads` trên một named volume; một host bind mount tại đường dẫn đó phải có quyền ghi cho uid này.

Mở rộng quy mô theo chiều ngang phía sau bất kỳ load balancer nào. Client cung cấp khóa của họ trong mỗi request, do đó không có sticky session. Với `offload_large`, hãy trỏ `FOURA_MCP_PAYLOADS_DIR` đến bộ lưu trữ dùng chung cho mọi instance, vì payload đã lưu nằm trên đĩa của instance đã ghi payload đó. `GET /healthz` phản hồi với `ok`, `name` và `version`, để load balancer có thể kiểm tra trạng thái instance.
