MCPサーバー

MCP Server

任意のModel Context Protocolクライアント(Claude Desktop、Claude Code、Cursor、Windsurf、VS Code)から、FourAを4つのネイティブツールおよび6つのワークフロープロンプトとして使用できます。統合コードやカスタムHTTPクライアントは不要です。

GitHubでオープンソースとして公開されており、npmでは@fouradata/mcpとして提供されています。現在のリリース: 0.5.0。

クイックスタート: ローカルstdio (Claude Desktopに推奨)

foura.ai/dashboard#api-keysでキーを取得します(ワンクリック、作成時に1度だけ表示、フォーマットはpk_live_...)。これを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`

クライアントを再起動します。ツールリストにツール(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 レスポンス)
認証	リクエストごとの `Authorization: Bearer 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", resource_metadata="https://foura.ai/docs/mcp/server#auth"`

ホストされたサーバーはステートレスです。各リクエストには独自のキーが含まれ、サーバーはそれを 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 を送信せず、そのまま通過します。

ツール

MCP 2025-06-18 仕様に従って、4つのツールすべてに readOnlyHint: true および openWorldHint: true というアノテーションが付けられています。信頼できる読み取り専用ツールを自動承認するクライアントは、リクエストごとの確認モーダルなしでそれらを呼び出します。

foura_auto はスマートなデフォルトです。URL を指定すると、フェッチ方法が自動的に選択され、コンテンツが返されます。他の3つは、それをオーケストレーションするための低レベルのプリミティブです。明示的な制御が必要な場合は、これらを使用します。

foura_auto

FourA にリクエスト方法を選択させたい場合は、URL を指定します。利用可能な HTTP、プロキシ、およびブラウザのパス全体で、制限付きの試行を行います。保護されたターゲットでは validate を渡すことで、実際のページを識別するコンテンツがレスポンスに含まれている必要があります。どの試行も検証を満たさない場合、ツールはチャレンジページを成功として提示する代わりにエラーを返します。

レスポンスには、meta の完了の詳細と、デフォルトでは、proxy、cookies、および userAgent を含む再利用可能な session が含まれます。プレーンなフォローアップの場合は、session.proxy を proxy として foura_single を呼び出し、Cookie を Cookie ヘッダーとしてシリアライズし、session.userAgent を User-Agent ヘッダーとして送信します。JavaScript レンダリングの場合は、セッション値を一致する foura_browser フィールドに渡します。

foura_single

1つの HTTP リクエスト、レスポンスが返されます。POST /api/single/ と1対1で対応しています。

静的ページ、JSON API、サーバーレンダリング HTML に使用します。

提示するブラウザの選択

リクエストはデフォルトで最新の Google Chrome を提示します。ターゲットが1つのブラウザを許可し、別のブラウザを拒否する場合は、browser (Chrome, Edge, Safari, Firefox, または Tor)、os (Windows, macOS, Android, または iOS)、または version を設定するか、正確な profile id を渡します:

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

複数のプロファイルが一致する場合、最新バージョンが適用されます。存在しない組み合わせの場合は利用可能なリストを含むエラーが返されるため、選択していないブラウザとしてrequestが送信されることはありません。選択にはunblockerが必要ですが、これはデフォルトで有効になっています。カタログはGET /api/profilesで公開されており、API keyは不要です。

同じ4つのフィールドがfoura_proxyのrequestオブジェクト内にあります。

foura_proxy

自動再試行を備えたローテーティングproxyを経由して、1つのHTTP requestをルーティングします。foura_singleがブロックされている場合や、ターゲットが特定の出口国を要求する場合に使用します。

ユーザーまたはターゲットの要件によって提供される、ターゲットから見える2文字の国コードの厳密な許可リストにexitCountriesを設定します:

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

値はトリミング、大文字化、および重複排除されます。不明な出口を持つproxyは除外され、requestが要求されていない国にフォールバックすることはありません。選択には、通常10分以内に更新される、ターゲットから見える最新の国メタデータが使用されます。これはrequest中のライブなジオロケーションのルックアップではありません。proxyのホストアドレスから提供国を推測しないでください。

スコープされた成功はexitCountryと再利用可能なproxy IDを返します。exitCountryが要求された許可リストに属していることを確認してください。現在のプールに一致するものがない場合、ツールはdetails.exitCountriesに正規化されたスコープを含めてcode: "no_eligible_proxy"を返します。そのスコープを保持し、後で再試行してください。ユーザーが明示的に要件を変更した場合にのみ、それを変更または拡大してください。

選択したページで後でJavaScriptが必要になった場合は、返されたproxy IDをfoura_browser.proxyに渡し、ブラウザが同じ出口を再利用するようにします。

foura_browser

完全なブラウザセッション。JavaScriptが実行され、DOMがレンダリングされ、cookieが返されます。POST /api/browser/をミラーリングします。

シングルページアプリ、遅延読み込みコンテンツ、またはクリアに実際のブラウザを必要とするアンチボットチャレンジの背後にあるページに使用します。

各ツールの入力シェイプ、デフォルト値、および検証ルールについては、REST endpointリファレンスを参照してください。ツールスキーマはREST APIとフィールド単位で一致し、さらにMCP専用のoffload_largeオプトイン(以下を参照)が追加されています。

ターゲットがボットチェックを実行する場合

foura_singleおよびfoura_proxyは、ターゲットがbodyへの途中でボットチェックを実行した場合にdefenseを返します。defense.solved: trueはチェックが満たされ、dataが実際のページであることを意味します。falseはbodyがチャレンジページである可能性があることを意味します。チャレンジページをコンテンツとして扱うのではなく、別のブラウザ、OS、またはバージョンで再試行するか、foura_proxyまたはfoura_browserに移行してください。

型付きのresponse

すべてのツールresponseには、content(人間が読めるテキストの要約)とstructuredContent(ツールのoutputSchemaに対して検証された型付きJSON)の両方が含まれます。各ツールには固有のシェイプがあります。

foura_auto: シングルシェイプの{ status, headers, data }とmeta({ rung, solved, attempts, credits }、常に存在し、rungはcache、probe、proxy、browser、failのいずれか)、およびデフォルトでは低レベルのツールを通じたリプレイ用のsession({ proxy, cookies, userAgent })が追加されます。total_timeはありません。
foura_single: { status, headers, data, total_time, ... } (headerは配列であり、リダイレクトホップごとに1つのエントリ)
foura_proxy: シングルと同じで{ proxy, total }が追加されます。スコープされた成功にはexitCountryも含まれます。
foura_browser: 異なるシェイプの{ status, headers: object, body, cookies, userAgent } (注: bodyはcontent-typeに応じて文字列またはオブジェクトになる場合があります)

structuredContentをサポートするクライアントは、LLMに文章からJSONを解析させる代わりに、型付きオブジェクトを直接LLMに渡すことができます。

複数値のresponse header

複数回出現するheader (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=/"]
    }
  ]
}

これは、1つのレスポンスでセッション、トラッキング、同意のcookieを設定するサイト（eコマースの大半）で重要です。

大規模なレスポンス: `offload_large` (デフォルト: inline)

デフォルト（v0.2.0以降）では、完全なレスポンスのbodyはサイズに関係なくstructuredContentでインラインで返されます。これは、すべてのMCPクライアントで設定なしに機能します。

クライアントがMCP resources/readをサポートしており、大きなページでトークンを節約したい場合は、ツール呼び出しごとにoffload_large: trueを渡します。50 KB以上のレスポンスはディスクに書き込まれ、resource_linkとして返され、クライアントは実際に必要な場合にのみbodyを取得します。キャッシュされたペイロードは1時間後に期限切れになります。

{
  "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 extension	対応

テナント分離: 各APIキーには独自のネームスペース(sha256(apiKey)[:16])が割り当てられます。ペイロードを保存したキーのみがそれを読み取ることができます。テナント間の読み取りは、存在の漏洩なしにPayload not foundを返します。

組み込みプロンプト

任意のMCPクライアントの/promptsに、6つのワークフローテンプレートが表示されます。それぞれが名前付き引数を受け取り、1つ以上のツールをオーケストレーションするテンプレート化されたユーザーメッセージを返します。

プロンプト	引数	機能
`smart_fetch`	`url`, オプション `must_contain`, `extract`	自動フェッチ(メソッドを選択し、ボット対策を処理)を行い、コンテンツを返すか抽出します
`scrape_product_page`	`url`	Browserフェッチを行い、製品のタイトル、価格、画像、在庫、SKUをJSONとして抽出します
`extract_article`	`url`	proxyフォールバック付きのSingle。ナビゲーションや広告を削除し、クリーンな記事JSONを返します
`monitor_pricing`	`url`, オプション `target_price`	proxyフェッチ。現在の価格を抽出し、目標と比較します
`check_endpoint_health`	`url`, オプション `expected_text`	厳格な検証付きのSingle。到達可能性とタイミングを返します
`bulk_fetch_urls`	`urls` (カンマ区切り)	並列Single。URLごとにproxyへ自動フォールバックし、メタデータのみを返します

待機時のプロンプトのトークン消費はゼロです。呼び出されたプロンプトのみがLLMコンテキストに入ります。

フルテキストと手動フォールバックプロンプト: MCP Recipes.

Errorエンベロープ

すべてのエラー(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エラーを参照してください。

安定したcodeの値:

コード	HTTP	意味	再試行可能か?
`ssrf_blocked`	n/a	プライベートまたは予約済み範囲(RFC 5735、6598、IPv6予約済み)のターゲットIP	いいえ、URLを変更してください
`upstream_non_json`	変動	アップストリームが不正な形式のボディを返した	多分、調査が必要
`output_validation_failed`	n/a	MCPサーバーの`outputSchema`がアップストリームの応答を拒否した(サーバーのバグまたは予期しないアップストリームの構造)	多分、報告が必要
`bad_request`	400	入力構造が拒否された	いいえ、引数を修正してください
`auth_failed`	401	キーがない、無効、または無効化されている	いいえ、キーを修正してください
`forbidden`	403	認証済みだが許可されていない	いいえ、または`foura_proxy`に切り替えてください
`not_found`	404	ターゲットまたはエンドポイントが見つからない	いいえ
`rate_limited`	429	RPM上限に達した	はい、`retryAfter`待機してください
`at_capacity`	503	同時実行上限に達した	はい、`retryAfter`待機してください
`service_disabled`	503	メンテナンス期間中、またはプランにこのツールが含まれていない	サポートに連絡してください
`service_unavailable`	503	一般的な503	はい、短いバックオフ
`upstream_error`	500+	アップストリームの5xx	はい、エクスポネンシャルバックオフ
`upstream_client_error`	4xx	その他の4xx	通常はいいえ
`upstream_unknown`	その他	防御的、実際には発生しないはず	調査が必要
`no_eligible_proxy`	n/a	厳密な`exitCountries`スコープに一致するプロキシがない	後で再試行。スコープは明示的にのみ変更してください

LLMエージェントは、散文を解析することなく、再試行ロジックのためにcodeを直接読み取ることができます。認証のウォークスルー: 認証。

制限

デフォルトでインラインボディ。offload_large: trueを使用すると、50 KB以上の応答はディスク + resource_link(テナントごと、1時間のTTL)に保存されます。
プライベートターゲット(RFC 5735、RFC 6598、IPv6予約済みブロック)はMCPレイヤーで拒否されます。パブリックホストのみ転送されます。
受信/mcpリクエストの256 KBのリクエストボディ上限(実際のMCPペイロードは < 4 KB)。
レート制限は、サービスごとにFourA APIによって適用されます。レート制限を参照してください。

セルフホスティング

完全なサーバーソースは、@fouradata/mcpの下でGitHubで公開されています。リポジトリをクローンし、npm install、npm run buildを実行し、node dist/http.jsを実行して独自のインスタンスを立ち上げます。任意のロードバランサーの背後にある単一のコンテナでステートレスに実行されます。

構成可能な環境:

変数	デフォルト	目的
`PORT`	`3076`	HTTPリッスンポート
`FOURA_API_BASE`	`https://api.foura.ai/api`	アップストリームFourA RESTベースURL
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	50KB以上のレスポンスがディスクにキャッシュされる場所(`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`	ブラウザ呼び出し元のオリジン許可リスト
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	401エラー時に`WWW-Authenticate`で返されるURL

公式コンテナはuid 1001(非root)として実行されます。/data/payloadsホストバインドマウントは、そのUIDによる書き込みが可能である必要があります。

任意のロードバランサーの背後で水平方向にスケーリングします。クライアントはすべてのリクエストでキーを提供するため、スティッキーセッションは不要です。

最終更新日: 2026年8月6日