MCP Server

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

クイックスタート：ローカル stdio（Claude Desktop に推奨）

foura.ai/dashboard#api-keys でキーを取得します（ワンクリックで取得でき、作成時に一度だけ表示されます。形式は 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 をダウンロードし（約10秒）、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_single、foura_proxy、foura_browser）と5つのプロンプトがツールリストに表示されます。

クイックスタート：ホスト型（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 ビルドは、生の url 形式を拒否します。Claude Desktop には上記の stdio 設定を使用するか、mcp-remote を経由してブリッジしてください。

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

ホスト型 endpoint リファレンス

プロパティ	値
URL	`https://mcp.foura.ai/mcp`
トランスポート	Streamable HTTP (POST `/mcp`, SSE responses)
認証	リクエストごとに `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"`

ホスト型サーバーはステートレスです。すべての request に独自のキーが含まれ、サーバーはそれを X-API-Key として FourA API に転送します。1つのキーで3つのツールすべてを利用できます。

DNS リバインディング（CVE-2025-66414）からの保護のため、サーバーは Host header（mcp.foura.ai または localhost である必要があります）と、存在する場合は Origin header（許可リスト：mcp.foura.ai、claude.ai、app.cursor.sh、app.cursor.com）を検証します。サーバー間呼び出し元（curl、stdio ブリッジモードの MCP クライアント）は Origin を送信せず、そのまま通過します。

ツール

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

foura_single

1回の HTTP request で response を返します。200ミリ秒から2秒。POST /api/single/ を1対1でミラーリングします。

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

foura_proxy

自動リトライ機能を備えたローテーション proxy プールを経由してルーティングされる HTTP request。1秒から5秒。POST /api/proxy/ をミラーリングします。

foura_single が 403、CAPTCHA、または地域制限されたコンテンツを返した場合に使用します。response には、成功した proxy ID（proxy）と、秒単位の外部実時間（total、浮動小数点数）が含まれます。

foura_browser

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

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

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

型定義された response

すべてのツール response には、content（人間が読めるテキストの概要）と structuredContent（ツールの outputSchema に対して検証された型定義済み JSON）の両方が含まれます。各ツールには独自の形状があります。

foura_single: { status, headers, data, total_time, ... }（headers は配列で、リダイレクトホップごとに1つのエントリ）
foura_proxy: single と同様、さらに { proxy, total }（total は秒単位の浮動小数点数、リトライを含む外部タイミング）
foura_browser: 異なる形状 { status, headers: object, body, cookies, userAgent }（注意：body は content-type に応じて文字列またはオブジェクトになります）

structuredContent をサポートするクライアント（2026年時点の Claude Desktop、Cursor、Windsurf）は、型定義されたオブジェクトを LLM に直接渡し、文字列としての JSON の再トークン化をスキップします。一般的な response では30〜40%のトークン削減が期待できます。

複数値の 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つの response でセッション、トラッキング、同意の cookie を設定するサイト（ほとんどの Eコマース）で重要になります。

大規模な response：`offload_large`（デフォルト：インライン）

デフォルト（v0.2.0以降）では、サイズに関係なく、完全な response body が structuredContent 内にインラインで返されます。これは、すべての MCP クライアントでそのまま動作します。

クライアントが MCP の resources/read をサポートしており、かつ大きなページでトークンを節約したい場合は、ツール呼び出しごとに offload_large: true を渡します。これにより、50 KB 以上の response はディスクに書き込まれ、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 拡張機能	サポート済み

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

組み込みプロンプト

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

プロンプト	引数	機能
`scrape_product_page`	`url`	ブラウザでの取得後、製品のタイトル、価格、画像、在庫、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。

エラーエンベロープ

すべてのエラー（isError: true）には structuredContent エンベロープが含まれます。すべてのエラーにおける最小限のフィールドは以下の通りです。

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

HTTP ステータスを伴うアップストリームエラーでは、status も存在します。rate limit およびキャパシティエラーでは、アップストリームエンベロープに retryAfter、current.{concurrency, rpm}、および limits.{maxConcurrency, maxRpm} が追加されます。基礎となる REST の形状については、API エラーを参照してください。

安定した code 値：

コード	HTTP	意味	再試行可能か？
`ssrf_blocked`	n/a	ターゲット IP がプライベートまたは予約済み範囲（RFC 5735、6598、IPv6 予約済み）内にある	いいえ、URL を変更してください
`upstream_non_json`	異なる	アップストリームが不正な形式の body を返した	おそらく可能、調査してください
`output_validation_failed`	n/a	MCP サーバーの `outputSchema` がアップストリームの response を拒否した（サーバーのバグまたは予期しないアップストリームの形状）	おそらく可能、報告してください
`bad_request`	400	入力形状が拒否された	いいえ、引数を修正してください
`auth_failed`	401	キーが見つからない、無効、または無効化されている	いいえ、キーを修正してください
`forbidden`	403	認証されたが許可されていない	いいえ、または `foura_proxy` に切り替えてください
`not_found`	404	ターゲットまたは endpoint が見つからない	いいえ
`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`	その他	防御的、実際には発生しないはずです	調査してください

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

制限事項

デフォルトでインライン body。offload_large: true の場合、50 KB 以上の response はディスクに保存され、resource_link が返されます（テナントごと、1時間の TTL）。
プライベートターゲットは、MCP レイヤーで拒否されます（RFC 5735、RFC 6598、IPv6 予約済みブロック）。パブリックホストのみが転送されます。
受信 /mcp リクエストに対する 256 KB の request body 制限（実際の MCP ペイロードは 4 KB 未満です）。
rate limit は、サービスごとに FourA API によって強制されます。Rate Limits を参照してください。

セルフホスト

各インスタンスは、1つのコンテナ内でステートレスに実行されます。公開 GitHub ミラーは v1.0 で提供される予定です。それまではソースはプライベートリポジトリにあり、コンテナイメージはリクエストに応じて利用可能です。早期アクセスについては、support@foura.ai までお問い合わせください。

設定可能な環境変数：

変数	デフォルト	目的
`PORT`	`3076`	HTTP 受信ポート
`FOURA_API_BASE`	`https://api.foura.ai/api`	アップストリームの FourA REST ベース URL
`FOURA_MCP_PAYLOADS_DIR`	`/data/payloads`	50 KB 以上の response がディスクにキャッシュされる場所（`offload_large: true` の場合）
`FOURA_MCP_ALLOWED_HOSTS`	`mcp.foura.ai,localhost,127.0.0.1,[::1]`	`Host` header のホスト名許可リスト（DNS リバインディング防御）
`FOURA_MCP_ALLOWED_ORIGINS`	`https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com`	ブラウザ呼び出し元の Origin 許可リスト
`FOURA_MCP_RESOURCE_METADATA_URL`	`https://foura.ai/docs/mcp/server#auth`	401 時に `WWW-Authenticate` で返される URL

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

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

最終更新日: 2026年7月1日

MCP Server

MCP Server

クイックスタート：ローカル stdio（Claude Desktop に推奨）

クイックスタート：ホスト型（Streamable HTTP）

ホスト型 endpoint リファレンス

ツール

foura_single

foura_proxy

foura_browser

型定義された response

複数値の response header

大規模な response：offload_large（デフォルト：インライン）

組み込みプロンプト

エラーエンベロープ

制限事項

セルフホスト

大規模な response：`offload_large`（デフォルト：インライン）