octen-mcp

octen-mcp

Octen 用の MCP サーバーです。Claude、Cursor、VS Code、Windsurf、または任意の MCP クライアントに接続すると、エージェントが最新のウェブ検索と URL 抽出を利用できます。

主な機能：

• search / news_search：ドメイン、テキスト、言語、時間のフィルターを使って、最新のウェブを検索します。
• broad_search：クエリを複数のサブクエリに分解して並行検索し、幅広くカバーできるよう、サブクエリごとに結果をまとめて返します。
• extract：1 つまたは複数の URL を、LLM で扱いやすいクリーンなコンテンツに変換します。
• image_search（ベータ版 — ベータへのアクセスをご希望の場合はお問い合わせください）：テキストクエリ、参照画像の URL、または base64 形式の画像データのうち、ちょうど 1 つを使って画像をウェブ検索します。
• video_search（ベータ版 — ベータへのアクセスをご希望の場合はお問い合わせください）：テキストクエリを使って動画をウェブ検索します。

Octen がエージェントに役立つのは、extract がページのテキスト以外も返すためです。成功した各結果には、次の情報も含まれます：

• category：ページの内容
• page_structure：ページの種類
• highlights：query を渡した場合に、関連度順で表示されるスニペット

これにより、エージェントは本文全体の処理にトークンを使う前に、ログイン画面、ナビゲーションページ、話題に関係のない URL を除外できます。

Octen MCP を選ぶ理由

高速

ウェブ検索の平均応答時間は 62ms です。複数ステップの MCP ワークフローにも十分な速さです。

高精度

最先端のテキストおよび VL 埋め込みモデルを活用しています。より質の高いソースを取得し、ハルシネーションを減らします。

最新

分単位で更新される、最新のウェブデータを利用できます。ニュース、価格、変化の速いページに便利です。

効率的

クリーンなハイライト、任意指定の full_content、ページラベルにより、モデルのコンテキストを関連性の高い内容に保てます。

クイックスタート

octen.ai から OCTEN_API_KEY を取得してください。ただし、クライアントが OAuth でサインインする場合は不要です（代わりにサインインするを参照）。

接続方法は 2 つあります。 どちらも同じ 6 つのツールを提供します。

	エンドポイント	利用する場面
ホスト型（推奨）	https://mcp.octen.ai/mcp	インストールや更新は不要です。リモート MCP に対応するあらゆるクライアントで動作します。
ローカル	npx -y octen-mcp	リモートに対応していないクライアント、外部ネットワークから隔離された環境、または自身のマシン上でプロセスを実行したい場合に利用します。

Node の互換性（ローカルのみ）： 0.4.2 以降は、Node 26 以降を含む、サポート対象のすべての Node（>= 18.17）で動作します。0.4.1 以前のバージョンは、組み込みの undici が v8 以降であるホスト（Node 26 以降）では、すべての呼び出しが次のエラーで失敗します：Network error … code=UND_ERR_INVALID_ARG cause=invalid onError method — このエラーが表示された場合は、パッケージを更新するか、Node <= 24 で実行してください。

ホスト型エンドポイントに接続する

キーを渡す

次の 3 つの方法があり、上から順に試されます。ヘッダーの使用を推奨します — URL 内のキーは、プロキシのログ、ブラウザーの履歴、Referer ヘッダーに記録される可能性があります。

形式	使用する場面
x-api-key: <key>	デフォルトです。
Authorization: Bearer <key>	クライアントがヘッダーフィールドを 1 つしか提供しない場合。
URL に追加した ?octenApiKey=<key>	クライアントが URL しか受け付けない場合。

または、キーを入力せずに OAuth を使うこともできます — 代わりにサインインするを参照してください。

クライアント別

Claude Code — プラグインをインストールします。ホスト型サーバーと 2 つのスキル、octen-web-search（リクエストを適切なツールにルーティング）と octen-research（複数の情報源を使った調査パイプライン）がまとめて含まれています。

claude plugin marketplace add Octen-Team/octen-mcp
claude plugin install octen@octen

または、セッション内から次を実行します：/plugin marketplace add Octen-Team/octen-mcp、続けて /plugin install octen@octen。

プラグインに認証情報は含まれていません。最初の呼び出しには 401 が返され、Claude Code が OAuth サインインを案内します。自分で開始する場合は /mcp を実行してください。 代わりに、キーを使ってサーバー単体を登録するには、次のようにします。

claude mcp add --transport http octen https://mcp.octen.ai/mcp --header "x-api-key: your-key-here"

Cursor — このリポジトリを Cursor のローカルプラグインディレクトリにクローンすると、 ホスト型サーバーと 2 つのスキルを一度に利用できます。

git clone https://github.com/Octen-Team/octen-mcp ~/.cursor/plugins/local/octen

Cursor Marketplace への掲載は審査中です。公開されたら、このセクションからリンクします。 サーバーだけを接続するには、~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "octen": {
      "url": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

VS Code — ワークスペースの .vscode/mcp.json またはユーザー設定を使用します。mcpServers ではなく servers を使い、type を明示してください。

{
  "servers": {
    "octen": {
      "type": "http",
      "url": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Codex

codex mcp add octen --url https://mcp.octen.ai/mcp --header "x-api-key: your-key-here"

Windsurf / Devin Desktop — macOS と Linux では ~/.config/devin/mcp_config.json を使用します（$XDG_CONFIG_HOME が設定されている場合は $XDG_CONFIG_HOME/devin/）。Windows では %APPDATA%\devin\mcp_config.json を使用します。 Cascade はリモートサーバーの設定に serverUrl と url のどちらも使えます。 レガシーエージェントのパスは ~/.codeium/windsurf/mcp_config.json です。

{
  "mcpServers": {
    "octen": {
      "serverUrl": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Gemini CLI — ~/.gemini/settings.json を使用します。キーは httpUrl です。

{
  "mcpServers": {
    "octen": {
      "httpUrl": "https://mcp.octen.ai/mcp",
      "headers": { "x-api-key": "your-key-here" }
    }
  }
}

Claude Desktop は URL を直接受け取るため、設定ファイルもブリッジも必要ありません。 Settings → Connectors で Add custom connector をクリックし、名前に Octen を指定して、 次を入力します。

https://mcp.octen.ai/mcp

Advanced settings は空欄のままにします。OAuth Client ID と Secret の各フィールドは、 クライアントを独自に登録できないサーバー向けのものですが、このサーバーは登録できます。 Claude からサインインを求められ、承認すると、その接続用の Octen キーが発行されます。

コネクターのダイアログにはリクエストヘッダーを入力する欄がないため、API キーは URL に含めます。

https://mcp.octen.ai/mcp?octenApiKey=your-key-here

2 つの方法では、サインインのほうがおすすめです。URL は秘密情報を安全に運ぶ手段ではなく、 サインインはアカウントから取り消せるため、こちら側で何も変更する必要がありません。 また、Claude はお使いのマシンではなく Anthropic のサーバーから接続します。そのため、 セルフホスト型のデプロイを利用するには、接続先にパブリックインターネットからアクセスできる必要があります。 プライベートなサーバーの場合は、以下のブリッジを使用してください。

Zed、Warp、Raycast、Cline はすべてリモートサーバーに直接接続します。 エンドポイントを指定してサインインしてください。Raycast の HTTP トランスポートには OAuth のタイプとして Dynamic があり、これを選びます。このサーバーは動的な クライアント登録に対応しているため、クライアント ID を用意する必要はありません。

{
  "mcpServers": {
    "octen": {
      "url": "https://mcp.octen.ai/mcp"
    }
  }
}

ヘッダーの入力欄がないクライアントでは、代わりにキーを URL に指定します： https://mcp.octen.ai/mcp?octenApiKey=your-key-here。

リモートサーバーにどうしても接続できないクライアントに限り、 mcp-remote ブリッジをローカルで実行して各リクエストを転送します。 --header のコロンの後にスペースを入れないでください。値は最初のコロンで分割されます。

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.octen.ai/mcp",
        "--header", "x-api-key:your-key-here"
      ]
    }
  }
}

サインインする場合

デプロイで認可サーバーが設定されている場合（ホスト型のデプロイでは設定されています）、 認証情報のないリクエストには 401 と WWW-Authenticate: Bearer resource_metadata="…" が返されます。これは MCP クライアントが OAuth フローを開始するために使うシグナルです。そのため、OAuth に対応する クライアントでは、キーを求める代わりにサインインが案内されます。

すでにキーを使っている接続を OAuth に切り替えるには、 https://mcp.octen.ai/mcp/oauth を接続先に指定するか、?login を追加します。このパスは キーが設定されていてもチャレンジを発行します。これが切り替えを開始する唯一の方法です。 キーが付いている場合、通常のエンドポイントから切り替えが促されることはありません。

読み込むツールを減らす

?tools=search,extract を指定すると、tools/list と tools/call の両方で、指定したツールだけに接続を制限できます。

https://mcp.octen.ai/mcp?tools=search,extract

クライアントは、公開されているすべてのツールの完全なスキーマをモデルのコンテキストに読み込むため、必要なツールが1つか2つだけの場合は、対象を絞ることで実際に節約できます。存在しない名前を指定すると、接続がひそかに不完全な状態で確立されるのではなく、有効な名前の一覧を含む 400 が返されます。

代わりにローカルで実行する

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": { "OCTEN_API_KEY": "your-key-here" }
    }
  }
}

エージェント	1行でインストール
Claude Code	claude mcp add --scope user octen -e OCTEN_API_KEY=your-key-here -- npx -y octen-mcp
Codex	codex mcp add octen --env OCTEN_API_KEY=your-key-here -- npx -y octen-mcp
Gemini CLI	gemini mcp add octen -e OCTEN_API_KEY=your-key-here -- npx -y octen-mcp
VS Code	code --add-mcp '{"name":"octen","command":"npx","args":["-y","octen-mcp"],"env":{"OCTEN_API_KEY":"your-key-here"}}'（または上のバッジをクリック）
Cursor	Cursor に追加（その後、キーを編集）、または上記の JSON を ~/.cursor/mcp.json に使用
Claude Desktop	CLI はありません。ホストされたエンドポイントを使う場合は 設定 → コネクタ → カスタムコネクタを追加（上記）を選択します。ローカルにインストールする場合は、設定ファイル（下記）を使用します

設定ファイルの場所

• Claude Desktop：~/Library/Application\ Support/Claude/claude_desktop_config.json — ローカル（stdio）インストールの場合にのみ必要です。ホストされたエンドポイントは、代わりにコネクタとして追加します
• Cursor：~/.cursor/mcp.json
• VS Code ワークスペース：.vscode/mcp.json（mcpServers の代わりに servers を使用）
• Windsurf：~/.codeium/windsurf/mcp_config.json
• Gemini CLI：~/.gemini/settings.json
• Cline／その他のクライアント：そのクライアントの MCP 設定に貼り付けます

トラブルシューティング

すべての呼び出しで 401 が発生する。 認証情報がサーバーに届いていないか、サインインが完了していません。サインインするクライアントでは、MCP 設定から接続を認証してください。キーを渡すクライアントでは、ヘッダー名（x-api-key または Authorization: Bearer）を確認してください。また、mcp-remote を使用している場合は、--header のコロンの後にスペースがないことを確認してください。

ツールが表示されない。 ほとんどのクライアントは起動時に MCP 設定を一度だけ読み込みます。設定を編集した後はクライアントを再起動してください。設定でクライアントに誤ったキー（url と serverUrl と httpUrl の違い）が使われていると、サーバーには一切接続されません。上記のクライアントごとのセクションを参照してください。

406 Not Acceptable が発生する。 リクエストの Accept ヘッダーには、application/json と text/event-stream の両方を指定する必要があります。クライアントは自動で指定しますが、手動で作成した curl による確認では通常指定されないため、結果として発生する 406 が認証エラーのように見えることがあります。

tools に言及する 400 が発生する。 ?tools= に指定された名前は、このデプロイで提供されていません。エラーには、提供されている名前が一覧表示されます。

ツールで code=403 … beta access を含むエラーが発生する。 image_search と video_search はベータ版で、アカウントごとに有効化されます。メッセージに申請方法が記載されています。

エラーには何が起きたかが記載されます。 呼び出しに失敗すると、どの依存先で、タイムアウト、接続コード、トークンの有効期限切れとその経過時間など、どのような理由で失敗したかが報告されます。また、API から返された場合は Octen 独自の request_id も含まれます。サポートへの問い合わせには、その ID を記載してください。エンジニアが検索できる ID です。

ツール

ツール	機能	最適な用途
search	ドメイン、テキスト、言語（ISO 639-1）、時間、コンテンツの条件を指定して、ウェブをリアルタイム検索します	目的を絞ったウェブ検索
news_search	search と同じエンジンをニュース検索に限定して使用します	最新の出来事や速報性の高い報道
broad_search	クエリを最大 max_queries 個のサブクエリに分解し、並行して検索して、結果をグループ化して返します（language フィルターを含む、search と同じサブクエリごとのオプションを使用します）	複数の視点から行うリサーチ形式の調査
extract	1〜20 件の URL を取得し、整理されたコンテンツ、ラベル、任意のハイライトを返します	要約、RAG、事実の確認
image_search	ベータ版です。ベータ版の利用についてはお問い合わせください。 テキストクエリ（任意の参照用 image_url）でウェブ上の画像を検索します	写真や画像、視覚的な参考資料を探す
video_search	ベータ版です。ベータ版の利用についてはお問い合わせください。 テキストクエリでウェブ上の動画を検索します	動画、クリップ、映像素材を探す

この 6 つだけを提供しているのは、意図的なものです。Embeddings、chat completions、Answer、Research は Octen の API ですが、このサーバーでは意図的に公開していません。Python SDK または CLI から利用してください。エージェントに見えるツールはエージェントが使おうとするツールであるため、ツール一覧には採用に値するものだけを載せています。

リファレンスドキュメント：

• Search：docs.octen.ai/api-reference/search
• Extract：docs.octen.ai/api-reference/extract

パラメーター

各ツールが公開するスキーマから転記したものであり、スキーマによって値が強制されます。そのため、契約に適合しない値は呼び出し前に拒否され、対象のフィールドを示すメッセージが表示されます。上限値は API リファレンスに準拠しており、両者に食い違いがあるとテストが失敗します。

image_searchでは、query、image_url、image_dataのうちいずれか1つだけを指定します。

queryは空でない必要があります。空文字列はスキーマによって拒否され、空白文字のみの文字列はハンドラーによって拒否されます。どちらもAPIには到達しません。

timeoutは2つの異なる意味を持ちます。 search、news_search、 broad_search、image_search、video_searchでは、このサーバー独自の呼び出し用HTTP期限です。リクエスト本文から削除され、APIには送信されません。一方、extractでは、APIで規定されたURLごとの取得時間枠（1～60秒）を意味し、本文にも含まれます。extract呼び出しのローカル期限は余裕を加えてこれを基に算出されるため、timeoutを増やすと両方の値が増加します。

重複するinclude_domainsとexclude_domainsは、指定されたとおりに渡されます。現在、APIは両方に記載されたドメインに対して検証エラーを返しますが、公開されている リファレンスでは、除外が優先されると説明されています。両者が一致するまでは、このサーバーはフィルターを暗黙に削除したり並べ替えたりしません。APIからの応答がそのまま返されます。

search

パラメーター	型	必須	上限	デフォルト
query	文字列	はい	1～500文字
topic	文字列		general / news	"general"
count	整数		1～100	5
include_domains	配列		≤1200件、各≤60
exclude_domains	配列		≤1200件、各≤60
include_text	配列		≤5件、各≤30
exclude_text	配列		≤5件、各≤30
time_basis	文字列		auto / published / crawled	"auto"
time_range	文字列		day / week / month / year / d / w / m / y
start_time	文字列
end_time	文字列
format	文字列		text / markdown	"text"
safesearch	文字列		off / strict	"strict"
language	配列			[]
highlight	オブジェクト		enable、max_tokens
full_content	オブジェクト		enable、max_tokens
include_images	ブール値			false
timeout	整数		1～60

news_search

パラメーター	型	必須	上限	デフォルト
query	文字列	はい	1～500文字
count	整数		1～100	5
include_domains	配列		≤1200件、各≤60
exclude_domains	配列		≤1200件、各≤60
include_text	配列		≤5件、各≤30
exclude_text	配列		≤5件、各≤30
time_basis	文字列		auto / published / crawled	"auto"
time_range	文字列		day / week / month / year / d / w / m / y
start_time	文字列
end_time	文字列
format	文字列		text / markdown	"text"
safesearch	文字列		off / strict	"strict"
language	配列			[]
highlight	オブジェクト		enable、max_tokens
full_content	オブジェクト		enable、max_tokens
include_images	ブール値			false
timeout	整数		1～60

broad_search

パラメーター	型	必須	制限	デフォルト
query	string	はい	1–500 chars
max_queries	integer		1–30	5
topic	string		general / news	"general"
count	integer		1–100	5
include_domains	array		≤1200 items; each ≤60
exclude_domains	array		≤1200 items; each ≤60
include_text	array		≤5 items; each ≤30
exclude_text	array		≤5 items; each ≤30
time_basis	string		auto / published / crawled	"auto"
time_range	string		day / week / month / year / d / w / m / y
start_time	string
end_time	string
format	string		text / markdown	"text"
safesearch	string		off / strict	"strict"
language	array			[]
highlight	object		enable, max_tokens
full_content	object		enable, max_tokens
include_images	boolean			false
timeout	integer		1–300

extract

パラメーター	型	必須	制限	デフォルト
urls	array	はい	≤20 items; each ≤2048
query	string		≤500 chars
max_age_seconds	integer		300–31536000	86400
format	string		markdown / text	"markdown"
timeout	integer		1–60	30
include_images	boolean			false
include_videos	boolean			false
include_audio	boolean			false
mode	string		standard / advanced / auto	省略（API は standard を使用）
include_links	object		scope（prefer_internal / prefer_external）、max_links（1–1000）	{} → prefer_internal、200

mode の選択：

シナリオ	mode
ニュース／ブログ／ドキュメント／製品ページ（一般的なサイト）	standard（または省略）
問題が発生しやすいと分かっているサイト（Reddit / X / LinkedIn / ResearchGate / ボット対策 / SPA）	advanced
混在した一括処理で、問題が発生しやすいサイトが不明	auto
コストを重視し、一般的なサイトが大半	standard
品質を優先し、問題が発生しやすいサイトが大半	advanced

standard は、問題が発生しやすいサイトで、コンテンツが空またはごくわずかでも success を返すことがあります。その場合は該当する URL のみを advanced で再試行してください。advanced は処理が遅く、standard の 2.5 倍の料金です。auto では、各 URL に実際に使用されたモードの料金が請求されます。advanced または auto を使用する場合は、timeout を長めに設定してください（例：60）。各結果には resolved_mode が表示されます。また、メタ行の billed: の件数は meta.usage.successful_by_mode に基づいており、これが請求の正確な基準です。

image_search

パラメーター	型	必須	制限	デフォルト
query	string		≤500 chars
image_url	string
image_data	string		≤5242880 chars
topic	string		general / design	"general"
count	integer		1–10	5
include_domains	array
exclude_domains	array
safesearch	string		off / strict	"strict"
html_snippet	object		enable, max_tokens
timeout	integer		1–60

video_search

パラメーター	型	必須	制限	デフォルト
query	string	はい	1–500 chars
count	integer		1–10	5
time_range	string		day / week / month / year / d / w / m / y
start_time	string
end_time	string
safesearch	string		off / strict	"strict"
timeout	integer		1–60

ツールを常に読み込む（任意）

MCP ツール検索が有効なクライアント（Claude Code のデフォルト）では、ツールは遅延読み込みされます。モデルは必要に応じて読み込むために ToolSearch ステップを実行します。最初のターンから Octen のツールを読み込んでおきたい場合（検出ステップなし）は、.mcp.json のサーバーで alwaysLoad を設定します（Claude Code v2.1.121 以降）。

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": { "OCTEN_API_KEY": "your-key-here" },
      "alwaysLoad": true
    }
  }
}

常に読み込まれるツールは、毎ターンコンテキストを消費します。また、alwaysLoad を設定するとサーバーへの接続が完了するまで起動がブロックされます（接続タイムアウトは約5秒が上限です）。そのため、頻繁に使うツールに限って設定してください。コストを抑えるには、各ツールの _meta で "anthropic/alwaysLoad": true を設定するツールを、たとえば search や broad_search など、利用頻度の高いものだけにして、残りは遅延読み込みのままにします。

エージェントに選ばれる理由

多くの抽出ツールは「ページ本文はこちらです」で終わります。Octen は、その一歩手前から支援します。

• 不適切なページを早期に除外：page_structure.primary == "No Main Content" は、エージェントがログイン画面や空のシェルなど、コンテンツのないページに到達したことを示します。
• トピックで早期に絞り込み：category を使うと、埋め込みや要約の前に、パイプラインで対象の業界に該当しないページを除外できます。
• コンテキストの使用量を削減：ユーザーがページ全体ではなく特定の事実を求めている場合、query は highlights を返します。

詳しい判断フローと統合パターンについては、docs/best-practices.md を参照してください。

プロンプトの例

• octen.ai を取得して、主な製品機能を要約してください。
• 過去1週間の最近の MCP ニュースを検索してください。
• これらの URL を取得し、カテゴリが Finance のものだけを要約してください。
• site:docs.anthropic.com prompt caching を検索し、関連するハイライトだけを返してください。

HTTP サーバーのセルフホスト

上記のホスト型エンドポイントは同じコードを実行しています。代わりに、自分で実行することもできます。

PORT=8080 npx -y -p octen-mcp octen-mcp-http   # or: octen-mcp-http after a global install

エンドポイント：POST /mcp（ステートレスな Streamable HTTP）と GET /healthz。設計上ステートレスのため、失われるセッションはありません。ロードバランサーの背後で複数のインスタンスを実行すればスケールできます。認証情報はリクエストごとに送信され、サーバー自体の環境変数から取得されることはありません。認証情報のないリクエストは、ホストのキーを暗黙のうちに消費するのではなく、失敗します。

認可は設定しない限り無効です。 OCTEN_OAUTH_AUTHORIZATION_SERVER と OCTEN_MCP_RESOURCE の両方を設定すると、サーバーは RFC 9728 の保護リソースメタデータを通知し、認証情報のないリクエストに 401 チャレンジを返します。未設定の場合は何も通知しません。インスタンスから、クライアントに対して実際には使用できない認可サーバーを案内してはなりません。その場合、不足しているキーは呼び出し時にエラーとして示されます。

引数の検証。 各ツールで宣言された inputSchema は、通知されるだけでなく実際に適用されます。型、範囲、文字列の長さ、配列のサイズ、列挙値、必須パラメーター、およびプロパティ一覧自体が検証されます。契約に適合しない呼び出しは、API に送信される前に、該当フィールドを示すメッセージとともに拒否されます。

画像を base64 で送信する場合。 image_search は、エンコード後に最大 5MB の image_data を受け付けます。これは JSON-RPC の本文に含まれて送信されます。未設定でも動作するよう、OCTEN_MCP_MAX_BODY のデフォルトは 6 MiB です。また、OCTEN_MCP_MAX_INFLIGHT_BODY（24 MiB）は、すべての処理中の本文が同時に保持できる合計サイズを別途制限します。リクエストごとの上限だけでは、多数のリクエストが同時に実行される場合に対応できないためです。

環境変数

変数	必須	デフォルト	備考
OCTEN_API_KEY	はい	—
OCTEN_API_URL	いいえ	https://api.octen.ai
OCTEN_ENABLE_BETA_TOOLS	いいえ	on	Beta の image_search / video_search ツールを検出対象から除外するには、false/0/off/no を設定します。
HTTPS_PROXY / HTTP_PROXY / NO_PROXY	いいえ	—	0.4.0 以降で有効です。Node 組み込みの fetch はデフォルトでこれらを無視するため、0.4.0 より前は、マシン上のほかのすべてのツールが接続できる場合でも、プロキシ経由ではサーバーが API に接続できませんでした。クライアント設定で明示的に設定してください — 詳細は以下を参照してください。ほとんどの MCP クライアントはシェル環境変数を引き継ぎません。
OCTEN_KEEP_ALIVE_MS	いいえ	60000	アイドル状態の接続を再利用のために維持する時間です。undici のデフォルト値である 4s では、ほぼすべての呼び出しで TLS ハンドシェイク（実測約 515ms）が再び必要になっていました。api.octen.ai での実測では、アイドル接続は 60s から 90s の間に閉じられます。これより短く保てば、接続先がすでに閉じたソケットにリクエストを送るのではなく、常に先に接続を解放できます。OCTEN_API_URL の接続先を変更する場合は、再測定してください。
OCTEN_KEEP_ALIVE_MAX_MS	いいえ	600000	接続先が独自の Keep-Alive ヒントを通知した場合に、上記の値に適用される上限です。api.octen.ai はこのヒントを送信しません。
OCTEN_CONNECT_TIMEOUT_MS	いいえ	10000	api.octen.ai への外向き接続の確立に対する上限時間です — 前述の MCP クライアント独自の起動時接続タイムアウトとは関係ありません。接続が断続的に失敗する経路では、値を小さく（例：5000）すると、自動再試行がより早く開始されます。
OCTEN_RETRY	いいえ	on	接続レベルの障害に対する自動再試行を 1 回行わないようにするには、false/0/off/no を設定します。元のリクエストが実際にはサーバーに到達していた場合、再試行によってクォータを消費します。
OCTEN_HTTP2	いいえ	off	HTTP/2 を有効にします。通常の一度に 1 リクエストを行うパターンでは速度の向上は実測されておらず、すべての CONNECT プロキシで安定して動作するわけではありません — 多数のツール呼び出しを並列で行う場合は、試す価値があります。
OCTEN_MCP_DEBUG	いいえ	off	stderr へのリクエストトレースです（stdout は MCP のフレーミングに使用されます）。詳細は以下を参照してください。

リモート HTTP 形式のみ

これらは octen-mcp-http だけが読み取ります。stdio エントリでは無視されます。

変数	必須	デフォルト	備考
PORT	いいえ	8080	0 を指定すると、エフェメラルポートが選択されます。
OCTEN_MCP_LOG	いいえ	人間が読めるテキスト	json を指定すると、ログパイプライン向けにイベントごとに JSON オブジェクトを 1 つ出力します。
OCTEN_MCP_MAX_BODY	いいえ	6291456	リクエストごとの本文サイズ上限（バイト単位）。受信したバイト数に対して適用されます。超過すると 413 が返されます。未設定でも image_search の image_data（エンコード後 5MB）が機能するサイズです。このデプロイで画像を送信しない場合は、値を下げてください。
OCTEN_MCP_MAX_INFLIGHT_BODY	いいえ	25165824	処理中のすべての本文が同時に保持できる合計バイト数の上限です。リクエストごとの上限は単一の巨大なリクエストを防ぎ、こちらは多数の通常のリクエストを防ぎます。超過すると 503 と Retry-After が返されます。実測では、base64 の本文が UTF-16 文字列として 2～3 回存在するため、常駐メモリの消費量はこの値のおよそ 10 倍になります。
OCTEN_MCP_BODY_DRAIN_MS	いいえ	2000	413 の後、413 自体が確実に配信されるよう、本文の残りを破棄し続ける時間です。
OCTEN_DRAIN_TIMEOUT_MS	いいえ	310000	SIGTERM の受信後、処理中の呼び出しが完了するまで待つ時間です。ポッドの terminationGracePeriodSeconds より短く、最長のツール実行時間（broad_search の 300 秒）より長くする必要があります。
OCTEN_APPS_CHALLENGE_TOKEN	いいえ	—	プラグインディレクトリのドメイン検証トークンです。設定すると、GET /.well-known/openai-apps-challenge はこの値をプレーンテキストとしてそのまま返します（本文はトークンのみである必要があります）。未設定の場合、このパスは 404 を返します。PRM と同様、設計上は匿名で利用できます。このトークンは、デプロイの秘密情報ではなく、ディレクトリが自身の検証機能で読み取るために生成します。

OAuth。 最初の 2 つを両方設定しない限り無効です。そのため、インスタンスが存在しない認可サーバーを通知することはありません。

変数	必須	デフォルト	備考
OCTEN_OAUTH_AUTHORIZATION_SERVER	OAuth では必須	—	認可サーバーのベース URL です。トークンの iss とバイト単位で比較し、JWKS URL の構築にも使用します。末尾にスラッシュを付けないでください。付けた場合、すべてのトークンを拒否することになるため、プロセスの起動が拒否されます。
OCTEN_MCP_RESOURCE	OAuth では必須	—	このデプロイの公開 URL（例：https://mcp.example.com/mcp）です。トークンの aud（RFC 8707）とバイト単位で比較されるため、末尾に余分なスラッシュがあると、すべての呼び出しが失敗します。プロキシの背後では推測できないため、明示的な指定が必要です。
OCTEN_OAUTH_RESOLVE_URL	OAuth では必須	—	グラントを API キーに交換する内部エンドポイントです。プライベートネットワーク経由で到達できる必要があります。公開アドレスでは利用できません。
OCTEN_OAUTH_RESOLVE_TOKEN	OAuth では必須	—	X-Octen-Service-Token としてそのエンドポイントに送信する共有シークレットです。
OCTEN_OAUTH_RESOLVE_CACHE_TTL_MS	いいえ	60000	解決済みのグラントを再利用する時間です。これは失効の伝播にかかる時間であり、今失効させたトークンも最長でこの時間だけ有効なままです。0 にすると呼び出しのたびに解決しますが、すべてのツール呼び出しの前にそのサービスを経由することになります。
OCTEN_JWKS_REFETCH_COOLDOWN_MS	いいえ	10000	不明なキー ID をトリガーとして JWKS を再取得する間隔の下限です。トリガーとなるのは未検証のトークンヘッダーです。下限がない場合、そのようなリクエストのたびに認可サーバーへのリクエストが発生します。この値を下げると、その割合に応じて発生頻度が高まります。

Claude Desktop での設定方法（およびログの出力先）

MCP サーバーはシェル環境を継承しません。Claude Desktop は HOME、LOGNAME、PATH、SHELL、USER と、サーバーの env ブロックに指定した値だけを渡して起動します。システム全体で設定したプロキシは引き継がれません。API キーとともに、明示的に指定する必要があります。

{
  "mcpServers": {
    "octen": {
      "command": "npx",
      "args": ["-y", "octen-mcp"],
      "env": {
        "OCTEN_API_KEY": "your-key-here",
        "HTTPS_PROXY": "http://proxy.example:8080"
      }
    }
  }
}

設定を編集したら、Claude Desktop を再起動してください。設定は起動時に読み込まれます。

サーバーの出力先：

• macOS：~/Library/Logs/Claude/mcp-server-octen.log
• Windows：%APPDATA%\Claude\logs\mcp-server-octen.log

以下のトレースを含め、サーバーが stderr に書き込むすべての内容がここに出力されます。

遅い、または失敗する呼び出しの診断

調査中は、上記の env ブロックに "OCTEN_MCP_DEBUG": "1" を追加し、 調査後は必ず削除してください。クライアントはローテーションされないログファイルに この情報を追記するため、有効のままにするとインストールしている間、ファイルが増え続けます。

有効にすると、すべての呼び出しが stderr に記録されます。

[octen-mcp 2026-08-14T04:36:36.219Z] call #1 received tool=search
[octen-mcp 2026-08-14T04:36:36.637Z] connect #1 established to api.octen.ai in 410ms peer=203.0.113.10:443 tls=TLSv1.3 alpn=http/1.1
[octen-mcp 2026-08-14T04:36:37.155Z] /search attempt=1 status=200 elapsed=935ms socket=new request_id=42cd56a5-…
[octen-mcp 2026-08-14T04:36:37.157Z] call #1 returning tool=search handler_total=938ms

各フィールドから、次のことがわかります。

• call #N received のタイムスタンプ — 呼び出しがこのプロセスに到達した時刻です。MCP クライアントがツール呼び出しを実行した時刻からこの時刻を差し引くと、その差はすべて octen-mcp の外部、つまりホストまたは両者の間で中継するものに費やされた時間です。クライアント側のストップウォッチだけでは、この時間とこちらが責任を負う時間を切り分けられません。
• connect … established in Xms — ハンドシェイクが行われ、その所要時間がわかります。connect FAILED の場合は、代わりにフェーズとエラーコードが示されます。
• peer= / tls= / alpn= — 接続が実際に到達したアドレス（API のホスト名はエニーキャストされるため、ホスト名だけではどのエッジに接続したかはわかりません）、およびネゴシエートされた TLS のバージョンとプロトコルです。これらが一致しない場合、ハンドシェイクが遅い、または失敗する原因がわからないままになることがあります。
• socket=new / socket=reused — この呼び出しでハンドシェイクが必要だったかどうかを示します。これにより、「サービスが遅い」のか「呼び出し間に接続が破棄された」のかを見分けられます。
• elapsed と handler_total — HTTP リクエストとツールハンドラーにそれぞれかかった時間です。大きな差がある場合、原因はネットワークではなく、リクエストの組み立てまたはレスポンスのフォーマットです。
• request_id — このトレース内だけで使われる、クライアントが生成した相関 ID です。再試行しても変わらず、呼び出しの試行をひも付けます。意図的に、ユーザー向けのエラーメッセージには表示されません。Octen のサポートではこの ID を検索できないためです（ゲートウェイがヘッダーを記録しません）。また、request_id というラベルの ID は、検索可能だと誤解されるおそれがあります。エラーメッセージに含まれるのは、Octen 側で検索できることが確認された ID のみです。現在該当するのは 1 つだけで、API エラーエンベロープに含まれるサーバー自身の request_id です。

失敗時には、fetch failed ではなく原因が示されます。

Network error calling Octen Search: code=ECONNREFUSED cause=connect ECONNREFUSED 203.0.113.9:443
address=203.0.113.9:443 — could not establish a connection.
If this machine requires an HTTP proxy, set HTTPS_PROXY.

UND_ERR_CONNECT_TIMEOUT は接続が確立されなかったこと、ECONNRESET は接続確立後に切断されたこと、ENOTFOUND は DNS の問題を意味します。これらは原因も担当箇所も異なる、3 つの別々の問題です。

リクエストのタイムアウト：search とメディアツールのデフォルトは 30 秒、broad_search は 120 秒（300 秒まで延長可能）、 extract は URL ごとの予算に余裕を加えた値です。検索ツールでは timeout パラメーターで 上書きできます。extract の timeout はサーバー側で URL ごとに設定される取得予算のため、 クライアントの上限はこれと同じ値ではなく、そこから算出されます。自動再試行では初回試行と同じ期限が使われるため、 指定したタイムアウトは再試行を含む呼び出し全体の上限です。

ローカル開発

git clone https://github.com/Octen-Team/octen-mcp.git
cd octen-mcp
npm install
npm run build
OCTEN_API_KEY=<key> npm run inspect

関連ドキュメント

• エージェント連携のベストプラクティス：docs/best-practices.md
• Search API リファレンス：docs.octen.ai/api-reference/search
• Extract API リファレンス：docs.octen.ai/api-reference/extract

ライセンス

MIT © Octen