MCPサーバー
MCPサーバー
任意のModel Context Protocolクライアント(Claude Desktop、Claude Code、Cursor、Windsurf、VS Code)から、4つのネイティブツールおよび6つのワークフロープロンプトとしてFourAを利用できます。統合コードやカスタムHTTPクライアントは不要です。
GitHubでオープンソース公開中。npmでは@fouradata/mcpとして提供。現在のリリース: 0.8.3。
クイックスタート: ローカルstdio(Claude Desktopに推奨)
foura.ai/dashboard#api-keysでキーを取得します(ワンクリック、フォーマットpk_live_...、Revealで後からキーを再表示可能)。お使いのMCPクライアントの設定に以下を追加してください:
{
"mcpServers": {
"foura": {
"command": "npx",
"args": ["-y", "@fouradata/mcp"],
"env": { "FOURA_API_KEY": "pk_live_..." }
}
}
}
Claude Desktopの注意点: 設定ファイルを編集する前に、Claude Desktopを完全に終了(macOSでは
Cmd+Q)してください。アプリが実行中の場合、終了時にメモリ内の設定で編集内容が上書きされます。
npxコマンドは初回起動時に@fouradata/mcpをダウンロードし、MCPクライアントのサブプロセスとして実行します。グローバルインストールは不要です。
| クライアント | 設定ファイルの場所 |
|---|---|
| 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 (先に環境変数でFOURA_API_KEYを設定) |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code (MCP拡張機能) | .vscode/mcp.json、mcpServersではなくトップレベルのserversキーの下 |
クライアントを再起動します。ツール(foura_auto、foura_single、foura_proxy、foura_browser)と6つのプロンプトがツールリストに表示されます。
クイックスタート: ホスト型 (Streamable HTTP)
Streamable HTTPトランスポートをサポートするクライアント(Cursor、Windsurf、VS Code、--transport httpを有効にしたClaude Code)の場合、ローカルのサブプロセスを実行する代わりにホスト型endpointを指定します:
{
"mcpServers": {
"foura": {
"url": "https://mcp.foura.ai/mcp",
"headers": {
"Authorization": "Bearer pk_live_..."
}
}
}
}
Claude Desktop の場合は、上記の stdio 設定を使用するか、ホストされた endpoint を mcp-remote 経由でブリッジします:
{
"mcpServers": {
"foura": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
}
}
}
ホスト型エンドポイントリファレンス
| プロパティ | 値 |
|---|---|
| URL | https://mcp.foura.ai/mcp |
| トランスポート | ストリーマブルHTTP (POST /mcp、SSEレスポンス) |
| 認証 | requestごとのAuthorization: Bearer pk_live_...。Authorization内のプレーンキー、またはX-API-Key: pk_live_...も利用可能 |
| MCP-Protocol-Version | @modelcontextprotocol/sdk準拠 (現在は2025-11-25、2025-06-18、2025-03-26、2024-11-05、2024-10-07) |
| 401チャレンジ | WWW-Authenticate: Bearer realm="foura-mcp" |
401チャレンジには、意図的にRFC 9728のresource_metadataパラメータを含めていません。これを通知すると、OAuth対応クライアントがこのサーバーで実装されていないフローを開始してしまうためです。pk_live_キーをBearerトークンとして送信すれば、401は解消されます。
ホスト型サーバーはステートレスです。すべてのrequestが独自のキーを保持し、サーバーはそのキーをX-API-KeyとしてFourA APIに転送します。1つのキーですべての4つのツールを利用できます。
DNSリバインディング (CVE-2025-66414) から保護するため、サーバーはHostヘッダー (mcp.foura.aiまたはlocalhostである必要があります) および存在する場合はOriginヘッダー (許可リスト: mcp.foura.ai、claude.ai、app.cursor.sh、app.cursor.com) を検証します。サーバー間呼び出し元 (curl、stdioブリッジモードのMCPクライアント) はOriginを送信せず、そのまま通過します。
ツール
4つのツールはすべて、MCP 2025-06-18仕様に従ってreadOnlyHint: trueおよびopenWorldHint: trueのアノテーションが付与されています。信頼できる読み取り専用ツールを自動承認するクライアントは、requestごとの確認モーダルなしでこれらを呼び出します。
foura_autoはスマートなデフォルトです。URLを渡すと、取得方法を自動で選択してコンテンツを返します。他の3つはオーケストレーションされる低レベルのプリミティブであり、明示的な制御が必要な場合に使用します。
foura_auto
FourAにrequest方法を選択させたい場合は、URLを渡します。利用可能なHTTP、proxy、ブラウザの各パスにわたって上限付きの試行を行います。保護されたターゲットではvalidateを渡して、実際のページを識別するコンテンツがresponseに含まれるようにします。どの試行も検証を満たさない場合、ツールはチャレンジページを成功として提示する代わりにエラーを返します。
responseにはmeta内の完了詳細が含まれ、デフォルトではproxy、cookies、userAgentを含む再利用可能なsessionが含まれます。プレーンな後続処理を行うには、foura_singleをproxyとしてsession.proxyを指定して呼び出し、cookieをCookieヘッダーとしてシリアライズし、session.userAgentをUser-Agentヘッダーとして送信します。JavaScriptレンダリングの場合は、対応するfoura_browserフィールドにセッション値を渡します。
標準プールでページにアクセスできない場合にAutoがプレミアムエグジットへエスカレーションできるようにするには、exitClass: "premium"を設定します。exitClass: "standard"を指定するかフィールドを省略すると、Autoは標準プールにとどまります。また、クラスを指定したrequestのみがexitClassを返します。これはfoura_proxyと同様に機能します。指示ではなく許容設定であり、プランのプレミアムトラフィックとしてカウントされ、プレミアムエグジットのないプランではcode: "plan_limit_premium"で拒否されます。結果のexitClassには、配信に使用されたクラスが示されます。Smart FetchのexitClassを参照してください。
foura_single
1つのHTTP requestを送信し、responseを受け取ります。POST /api/single/を1対1でミラーリングします。
静的ページ、JSON API、サーバーレンダリングされたHTMLに使用します。
提示するブラウザの選択
requestはデフォルトで最新のGoogle Chromeを提示します。ターゲットが特定のブラウザを受け入れ、別のブラウザを拒否する場合は、browser (Chrome、Edge、Safari、Firefox、またはTor)、os (Windows、macOS、Android、またはiOS)、versionを設定するか、正確なprofile IDを渡します。
{
"method": "GET",
"url": "https://example.com",
"browser": "Firefox",
"os": "Windows"
}
複数のプロファイルが一致する場合、最新のバージョンが優先されます。存在しない組み合わせの場合は利用可能な一覧を含むエラーを返すため、意図しないブラウザとしてリクエストが送信されることはありません。選択にはunblockerが必要ですが、これはデフォルトで有効です。カタログはGET /api/profilesで公開されており、APIキーは不要です。
同じ4つのフィールドがfoura_proxyのrequestオブジェクト内に配置されます。
foura_proxy
自動リトライ機能を備えたローテーションプロキシ経由で、1つのHTTPリクエストをルーティングします。foura_singleがブロックされている場合や、ターゲットが特定の出口国を必要とする場合に使用します。
exitCountriesには、ユーザーまたはターゲットの要件によって指定された、ターゲットから見える2文字の国コードの厳密な許可リストを設定します:
{
"maxTries": 5,
"exitCountries": ["CZ", "GB"],
"request": {
"method": "GET",
"url": "https://example.com/pricing",
"browser": "Chrome",
"os": "Windows"
}
}
値はトリミングされ、大文字に変換され、重複が排除されます。国が不明な standard プールの出口は除外され、standard プールが要求されていない国へフォールバックすることはありません。premium 出口もこのリスト内に留まります。exitClass: "premium" の場合、依然として standard プールが優先され、premium 出口は指定されたいずれかの国から出て、exitCountry でその国名を示します。選択には、通常10分以内に更新される、ターゲットから見える最新の利用可能な国のメタデータが使用されます。リクエスト時のリアルタイムな地理位置情報ルックアップではありません。proxy のホストアドレスから配信元の国を推測しないでください。
スコープ指定に成功すると、exitCountry と再利用可能な proxy IDが返されます。exitCountry が要求された許可リストに属していることを確認してください。現在のプールに一致するものがない場合、ツールは code: "no_eligible_proxy" を返し、details.exitCountries に正規化されたスコープを含めます。そのスコープを保持し、後で再試行してください。ユーザーが明示的に要件を変更した場合にのみ、スコープを変更または拡大してください。国のスコープ指定は Startup プラン以上で含まれます。これを含まないプランでは、exitCountries を送信する呼び出しは 403 および X-FourA-Limit: plan_limit_feature で拒否されます。
選択したページで後から JavaScript が必要になった場合は、返された proxy IDを foura_browser.proxy に渡し、ブラウザが同じ出口を再利用するようにします。
何度出口を試行しても standard プールでは到達できないターゲットに対しては、exitClass: "premium" を設定します。これは許可であり、強制的な指示ではありません。standard プールが引き続き応答を試み、通常はこちらが優先されます。premium 出口が試行される前に standard プールが応答したリクエストでは、premium トラフィックは消費されません。premium の試行では、失敗した場合でも転送されたトラフィックがカウントされます。レスポンスは exitClass(premium または standard)を返し、リクエストごとにどのクラスが処理したかを確認できます。プランに含まれる premium トラフィックを使い切った場合も standard が返されますが、これはエラーではなく正常な結果です。exitClass: "standard" はエスカレーションを完全に禁止します。premium 出口のないプランでの exitClass: "premium" は、code: "plan_limit_premium" で拒否されます。exitClass を参照してください。
応答を得るためにローテーションが別のブラウザへ切り替える必要があった場合、成功したレスポンスには最終的に選択されたカタログプロファイルIDである profile が含まれます。次回呼び出し時にこれを profile として渡すことで、同じブラウザを提示できます。
ローテーションに失敗した場合、エラーの横に attemptReport が付与されます。これには1つの summary 文言に加え、応答がなかった出口(noResponse)、bot チェックによって拒否された出口(defense、vendors にベンダーを記載)、到達したものの独自の validate.data によってのみ拒否されたページ(contentRejected)、statusRejected、および other を分類したカウントが含まれます。profilesTried には、タスクが送信したブラウザが初回使用順に一覧表示され、default はリクエストが記述どおりに送信されたことを意味します。contentRejected の値が高い場合は、FourA が実際のページを返したものの、独自ルールによって破棄されたことを意味します。Why a Proxy Request Ran Out of Tries を参照してください。
foura_browser
完全なブラウザセッション。JavaScriptを実行し、DOMをレンダリングし、cookieを取得します。POST /api/browser/を反映します。
シングルページアプリケーション、遅延ロードされるコンテンツ、または完了に実際のブラウザが必要なチェックを持つページに使用します。
各ツールの入力形式、デフォルト値、および検証ルールについては、RESTエンドポイントリファレンスを参照してください。ツールスキーマはREST APIと一致し、MCP限定のoffload_largeオプトイン(下記参照)が加わりますが、2つの例外があります。foura_browserにはleanフィールドがなく、foura_proxyにはexit locationフィールドがまだありません。それらの名前で送信された値がAPIに到達することはありません。設定するには、POST /api/browser/またはPOST /api/proxy/を直接呼び出してください。
ターゲットがbotチェックを実行する場合
foura_singleおよびfoura_proxyは、ターゲットがbodyへの到達途中でbotチェックを実行した場合にdefenseを返します。defense.solved: trueはチェックを通過し、dataが実際のページであることを意味します。falseはbodyがチャレンジページである可能性があることを意味します。チャレンジページをコンテンツとして扱うのではなく、異なるbrowser、os、versionで再試行するか、foura_proxyまたはfoura_browserに移行してください。
型定義されたレスポンス
すべてのツールレスポンスには、content(人間が読めるテキストサマリー)とstructuredContent(ツールのoutputSchemaに対して検証された型付きJSON)の両方が含まれます。各ツールは独自の形式を持ちます。
foura_auto: 単一形式の{ status, headers, data }に加え、meta({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }、常に存在、rungはcache、probe、proxy、browser、warmup、failのいずれか)、および下位レベルのツールを介してリプレイするためのデフォルトのsession({ proxy, cookies, userAgent })。クラスを指定したrequestにはexitClassも含まれます。meta.attemptsByEngineは呼び出しがSingle、Proxy、Browserに送信したrequestをカウントし、meta.browserRequestsは1日のBrowser許容量を消費したものをカウントします。失敗時にはattemptReportも含まれます。total_timeはありません。foura_single:{ status, headers, data, total_time, ... }(headersは配列で、リダイレクトホップごとに1エントリ)foura_proxy: singleと同様に加え{ proxy, total }。スコープ内の成功にはexitCountry、クラスを指定したrequestにはexitClass、ブラウザファミリーを変更したローテーションにはprofile、失敗時にはattemptReportが含まれますfoura_browser: 固有の形式{ status, headers: object, body, cookies, userAgent }(注:bodyはcontent-typeに応じて文字列またはオブジェクトになります)
すべてのツールは、APIのレスポンスヘッダーから読み取られた、呼び出しのコストとトレース方法もレポートします。
credits- この呼び出しで消費されたクレジットです。処理自体は実行されたため、失敗時にも表示されます。請求は成功した呼び出しに対してのみ行われるため、失敗時にはクレジット数がここに表示されても費用は発生しません。request_id- この呼び出しに対する FourA の ID です。サポートへの問い合わせ時に引用してください。exitClass- プレミアム出口が呼び出しを処理した場合はpremiumになります。foura_singleおよびfoura_browserでは、foura_proxyまたはfoura_autoが検出したプレミアム出口をproxyがリプレイするときに発生します。
API から何も報告されなかった場合は各項目とも省略されるため、旧バージョン向けに記述されたクライアントもそのまま変更なく動作します。同じ値が Response Headers に文書化されています。
structuredContent をサポートするクライアントは、文章から JSON を解析させる代わりに、型付きオブジェクトを直接 LLM に渡すことができます。
複数の値を持つレスポンスヘッダー
複数回出現するヘッダー(Set-Cookie、Link、WWW-Authenticate)は配列として返されます。
{
"headers": [
{
"result": { "version": "HTTP/2", "code": 200, "reason": "" },
"content-type": "text/html",
"set-cookie": ["a=1; Path=/", "b=2; Path=/"]
}
]
}
これは、単一のresponseでセッション、トラッキング、同意cookieを同時に設定するサイト(大半のEコマースなど)で重要になります。
大規模なresponse: offload_large (デフォルト: inline)
デフォルト(v0.2.0以降)では、サイズに関係なく完全なresponse bodyがstructuredContent内にインラインで返されます。これはすべてのMCPクライアントで設定なしで動作します。
クライアントがMCP resources/readをサポートしており、かつ大きなページでトークンを節約したい場合は、ツール呼び出しごとにoffload_large: trueを渡してください。50 KB以上のresponseはディスクに書き込まれ、resource_linkとして返されるため、クライアントは実際に必要になった場合にのみbodyを取得します。ホスト型サーバーでは、キャッシュされたペイロードは1時間後に期限切れになります。独自のインスタンスでは保存されたペイロードは自動削除されないため、ペイロードディレクトリから1時間以上経過したファイルを各自で削除してください。
オフロードされた結果には、bodyの代わりにoffloaded_resource_uriとsize_bytesが含まれます。また、オフロードされた結果ではdefenseやfoura_proxyのprofileも除外されるため、これらのフィールドを読み取る呼び出しではoffload_largeをスキップしてください。
{
"method": "GET",
"url": "https://en.wikipedia.org/wiki/Web_scraping",
"offload_large": true
}
| クライアント | offload_large: true |
|---|---|
| Claude Desktop | 未対応、デフォルトの false のままにしてください |
| Claude Code, Cursor, Windsurf | サポート対象 |
| VS Code MCP 拡張機能 | サポート対象 |
テナント分離: 各 API キーには専用の名前空間 (sha256(apiKey)[:16]) が割り当てられます。ペイロードを保存したキーのみがそれを読み取ることができます。テナント間の読み取りは、存在の漏洩を防ぐため Payload not found を返します。
組み込みプロンプト
任意の MCP クライアントの /prompts 配下に6つのワークフローテンプレートが提供されます。それぞれが名前付き引数を受け取り、1つ以上のツールをオーケストレーションするテンプレート化されたユーザーメッセージを返します。
| プロンプト | 引数 | 動作 |
|---|---|---|
smart_fetch |
url、オプション must_contain、extract |
自動取得(メソッドの自動選択、Bot対策の処理)、その後コンテンツの返却または抽出 |
scrape_product_page |
url |
ブラウザ取得後、商品名、価格、画像、在庫、SKU を JSON として抽出 |
extract_article |
url |
proxy フォールバック付き単一取得後、ナビゲーション/広告を削除してクリーンな記事 JSON を返却 |
monitor_pricing |
url、オプション target_price |
proxy 取得、現在の価格を抽出、目標価格と比較 |
check_endpoint_health |
url、オプション expected_text |
厳格な検証を伴う単一取得、到達可能性と所要時間を返却 |
bulk_fetch_urls |
urls (カンマ区切り) |
並行単一取得、URL ごとの proxy への自動フォールバック、メタデータのみ返却 |
プロンプトはアイドル時にはトークンを消費しません。呼び出されたプロンプトのみが LLM コンテキストに含まれます。
全文および手動フォールバックプロンプト: MCP レシピ。
エラーエンベロープ
すべてのエラー (isError: true) には structuredContent エンベロープが含まれます。各エラーの最小フィールド:
{
"service": "auto | single | proxy | browser",
"code": "rate_limited",
"error": "Rate limit exceeded"
}
HTTPステータスを伴うアップストリームエラーの場合、statusも含まれます。レート制限やキャパシティのエラーでは、アップストリームのエンベロープにretryAfter、current.{concurrency, rpm}、limits.{maxConcurrency, maxRpm}が追加されます。基盤となるRESTの構造についてはAPI Errorsを参照してください。
安定版のcodeの値:
| コード | HTTP | 意味 | 再試行可能か |
|---|---|---|---|
ssrf_blocked |
n/a | ターゲットがプライベートまたは予約済みアドレス(RFC 5735、6598、IPv6予約済み)である、URLがhttp(s)ではない、またはホスト名が解決されませんでした | 不可、URLを確認してください。一時的な名前解決の失敗であれば再試行可能です |
upstream_non_json |
変動 | アップストリームが無効なボディを返しました | 状況による、調査が必要です |
output_validation_failed |
n/a | MCPサーバーのoutputSchemaがアップストリームレスポンスを拒否したか、ツールが呼び出しを完了できませんでした(APIキー未設定、API到達不能など) |
状況による: 設定を確認後、報告してください |
bad_request |
400 | 入力形式が不正、ターゲットURLがウェブページではなくFourA自身のAPIを指している(ここでは/inspectのみ取得可能)、またはURL内にエンコードされていないスペースが含まれています(%20としてエンコードしてください) |
不可、引数を修正してください |
auth_failed |
401 | キーが見つからない、無効、または無効化されています | 不可、キーを修正してください |
forbidden |
403 | ターゲットが403を返し、validateによって拒否されました(サイトのチェック、国制限など) |
不可、またはfoura_proxyに切り替えてください |
not_found |
404 | ターゲットまたはエンドポイントが見つかりません | 不可 |
rate_limited |
429 | RPM上限に達しました | 可能、retryAfter待機してください |
at_capacity |
503 | 同時実行数の上限に達したか、メンテナンスのためサービスが停止しています(errorの値はService disabledです) |
可能、retryAfter待機してください |
service_disabled |
503 | 予約済み。現在、メンテナンスによるサービス停止はat_capacityとして返され、プランに含まれないツールはplan_limit_featureとして返されます |
サポートにお問い合わせください |
service_unavailable |
503 | 一般的な503エラー | 可能、短いバックオフ後に再試行 |
upstream_error |
500+ または 0 | ターゲットがサーバーエラーを返したか、foura_proxyにおいてfoura_browserおよびfoura_autoから応答がありませんでした |
可能、指数バックオフ後に再試行 |
upstream_client_error |
4xx | その他の4xx | 通常は不可 |
upstream_unknown |
その他 | リクエストは実行されたものの受け入れ可能な応答が得られませんでした: foura_singleでターゲットが応答しなかった(タイムアウト、接続拒否)、またはいずれかのツールでvalidateが2xxまたは3xxレスポンスを拒否しました。statusおよびerrorを確認してください |
調査が必要です |
no_eligible_proxy |
n/a | 厳密なexitCountriesスコープに一致するproxyがありません |
後で再試行してください。スコープの変更は明示的な場合のみ行ってください |
plan_limit_* |
403 または 429 | ご利用プランの制限により呼び出しが拒否されました: plan_limit_に続きfeature、premium、concurrency、rate、browser_daily、creditsまたはbandwidth。詳細はMCP Server Errorsを参照してください |
retryAfterが存在する場合は待機してください。それ以外の場合は制限がリセットされるかプランが変更されるまで不可です |
LLMエージェントは文章を解析することなく、リトライロジック用にcodeを直接読み取ることができます。認証手順: 認証。
制限事項
- デフォルトではインラインのbodyを返します。
offload_large: trueを使用すると、50 KB以上のレスポンスはディスク +resource_linkに出力されます (テナントごと、TTL 1時間)。 - プライベートターゲットはMCPレイヤーで拒絶されます (RFC 5735、RFC 6598、IPv6予約ブロック)。パブリックホストのみが転送されます。
- 受信する
/mcpリクエストのbody上限は256 KBです (実際のMCPペイロードは4 KB未満)。 - rate limitはサービスごとにFourA APIによって適用されます。Rate Limitsを参照してください。
セルフホスティング
サーバーの完全なソースは、@fouradata/mcpライセンスのもとGitHubで公開されています。リポジトリをクローンし、npm install、npm run buildを実行後、node dist/http.jsを実行することで独自のインスタンスを起動できます。任意のロードバランサーの配下で、単一コンテナとしてステートレスに動作します。
設定可能な環境変数:
| Variable | Default | Purpose |
|---|---|---|
PORT |
3076 |
HTTPリスンポート |
FOURA_API_BASE |
https://api.foura.ai/api |
アップストリームのFourA RESTベースURL |
FOURA_MCP_PAYLOADS_DIR |
システムの一時ディレクトリ内のfoura-mcp-payloadsフォルダー (バンドルされたDocker Composeファイルでは/data/payloadsを設定) |
50 KB以上のレスポンスをディスクにキャッシュする場所 (offload_large: true使用時) |
FOURA_MCP_ALLOWED_HOSTS |
mcp.foura.ai,localhost,127.0.0.1,[::1] |
Hostヘッダー用のホスト名許可リスト (DNSリバインディング対策) |
FOURA_MCP_ALLOWED_ORIGINS |
https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com |
ブラウザ呼び出し元用のOrigin許可リスト |
公式コンテナはuid 1001 (non-root) として実行されます。バンドルされたDocker Composeファイルは/data/payloadsを指定されたボリューム上に保持します。そのパスに対するホストのバインドマウントには、そのuidによる書き込み権限が必要です。
任意のロードバランサー配下で水平スケール可能です。クライアントはリクエストごとにキーを提供するため、スティッキーセッションは不要です。offload_largeを使用する場合、保存されたペイロードはそれを書き込んだインスタンスのディスク上に存在するため、FOURA_MCP_PAYLOADS_DIRには全インスタンスが共有するストレージを指定してください。GET /healthzはok、name、versionを返すため、ロードバランサーがインスタンスをプローブできます。