MCP Server
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 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; có trên npm 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 (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:
{
"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+Qtrê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ộ:
{
"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:
{
"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. 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.
foura_single
Một HTTP request, nhận lại response. Tương ứng một-một với POST /api/single/.
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:
{
"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 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:
{
"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.
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.
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/.
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. 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. 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/ hoặc POST /api/proxy/.
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 theometa({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, luôn có mặt, trong đórunglà 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ồmexitClass.meta.attemptsByEngineđếm số lượng request mà lệnh gọi đã gửi tới Single, Proxy và Browser, cònmeta.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ồmattemptReport. 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ồmexitCountry, một request có chỉ định class bao gồmexitClass, một lần luân phiên thay đổi nhóm browser bao gồmprofile, và khi thất bại bao gồmattemptReportfoura_browser: cấu trúc riêng biệt{ status, headers: object, body, cookies, userAgent }(lưu ý:bodycó 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:premiumkhi lệnh gọi được xử lý qua premium exit. Trênfoura_singlevàfoura_browser, điều này xảy ra khiproxyphát lại một premium exit màfoura_proxyhoặcfoura_autotì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.
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:
{
"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 đó.
{
"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.
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:
{
"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 để 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 |
Đợ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.
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
/mcpgử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.
Tự lưu trữ (Self-Hosting)
Toàn bộ mã nguồn máy chủ được công khai trên GitHub 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.