Grok MCP — エージェントスキルリファレンス
このファイルを使用して、どのツールを呼び出すか、どのモデルを使用するか、そしてGrokをまったく呼び出すべきでない場合を判断します。
デフォルトモデルはありません。各呼び出しでmodelを明示的に指定し、意図的に選択する必要があります。
タスクを実行できる最も安価なモデルを選択し、品質が不十分な場合のみ上位モデルに切り替えます。
Grok MCPを使用する場合と自分で実行する場合
| タスク | Grok MCPを使用 | 自分で実行 |
|---|---|---|
| ユーザーが明示的にGrokを要求 | ✅ 常にリクエストを尊重 | — |
| 画像を生成または編集 | ✅ 常に | ✗ ほとんどのモデルは画像生成不可 |
| ローカルファイル画像を分析 | ✅ agent(model=..., image_paths=[...]) | ✗ ファイルがディスク上にある必要あり |
| 大規模コードベース分析（>200Kトークン） | ✅ agent(model=<大規模コンテキスト>, tools=["read"]) | ✗ コンテキスト制限 |
| あなたの回答とGrokの回答を比較 | ✅ 両方を呼び出す | ✅ 両方を呼び出す |
| 一般的なテキスト/推論（非依頼） | ✗ 不必要なコスト | ✅ 優先 |
| コード生成（非依頼） | ✗ 現在のモデルが利用不可能でない限り | ✅ 優先 |
デフォルトルール：まず自分で実行する。以下の場合にGrokを使用する：
- ユーザーが明示的にGrokを要求した場合（例：「Grokに聞いて」「Grokを使って」「Grokで生成して」）
- 現在のモデルがタスクを実行できない場合（画像生成、ローカルファイルの視覚分析、コンテキスト不足）
- ユーザーがあなたの回答とGrokの回答を比較するよう要求した場合
モデルの選択 — 毎回の呼び出しで判断
Grokモデルを実行するすべてのツール（agent、質問付きread、shell、search、generate_image*）は**modelを必須とします**。ロール、デフォルト、autoルーターはありません。モデルが欠落しているか未知の場合、有効な選択肢のリストとともにエラーが返されます。
選択肢の出所： 各ツールの説明には、現在のxAIカタログ（ID、コンテキストウィンドウ、1Mトークンあたりの価格（通常およびキャッシュ）、画像入力を受け付けるモデルには[images]）がリストされています。このリストはサーバー起動時にライブのxAI APIから取得されます。list_models(refresh=true)でカタログを再取得し、変更点を報告してツールの説明を更新します。モデル名や価格を記憶に頼ってハードコードしないでください。必ずリストを読んでください。
ロールタグ。 サーバーはライブカタログからモデルをタグ付けします（名前によるものではありません）。これにより、以下のポリシーはモデルの入れ替え後も有効です。cheapest（最低価格）、flagship（最新世代、最も高機能で高価）、code（コード用に調整）。タグと表示された価格に基づいて選択します。
デフォルトポリシー — 安価に開始し、証拠がある場合のみエスカレート：
- ルーチンワーク（質問、要約、抽出、分類、コード編集、ファイルレビュー）
→
cheapestモデル、モデルが許容する場合はreasoning_effort="low"。 - 安価な実行結果が明らかに不十分な場合、またはタスクが多数のファイルにわたる深い多段階分析である場合にのみ、
flagshipにエスカレートします。「念のため」ではありません。 - 長時間またはツール多用の実行：
tools=["read"]+ 名前付きファイル、background=True、そして以下の見積もりから選択した明示的なmax_cost_usd。サーバーのデフォルトに依存しないでください。 - 結果を読む：
cost_usd、stopped、hint。hintは実行が早期終了したか、フラッグシップで高コストだったことを意味します。それに従い（cheapestで再試行、タスクを絞り込む）、同じ呼び出しを再実行しないでください。
| ニーズ | 選択 |
|---|---|
| 入力が約200Kトークンを超える | コンテキストウィンドウが適合するモデル — ctxを確認 |
| 画像入力 | [images]とマークされたモデル |
| 画像生成 | 最も安価な画像モデルで反復し、最終レンダリングは高品質モデルで |
コストゲート — すべてのagent() / read / shell / search呼び出しで必須
1. 最初に見積もり、それを伝える。 呼び出しの前に、ユーザーに1行を書く：
見積もり：〜<N>K入力トークン、〜<R>ラウンド、<model> → 〜$<X>。小さなシングルショット呼び出し（短い質問）の場合は1節で十分です（「〜2Kトークン、<$0.01」）。ツールの説明の価格から計算します（記憶に頼らないでください）：
- シングルショット（
toolsなし）：input_tokens × in-price + expected_output × out-price（1トークン ≈ 4文字；推論トークンは出力として請求されます）。 - ツールループ：各ラウンドで会話全体が再送信されるため、コストはラウンド数に応じて増加します。
rounds × average_context × cached-priceに、各ラウンドの新しいトークンと出力のコストを加算します。このセッションからの過去のcost_usd値が最良の較正基準です。理論よりもそれらを優先してください。 - 不明な場合？上限を取ります。これが
max_cost_usdとして渡す値です。
2. 2ドルを超える場合はユーザーの承認が必要。 見積もりが2ドルを超える場合、まだ呼び出さないでください。見積もり、モデル、そして安価な実行と比較して何が得られるかを示し、明示的な同意を待ちます。承認はそのタスクのみをカバーし、後続のタスクはカバーしません。2ドル以下の場合は、尋ねずに続行します。
3. 常にmax_cost_usdを渡す： 見積もり + 約30%の余裕、上限は2ドル（ユーザーがそれ以上の承認をした場合は、承認された最大金額まで）。サーバーのGROK_MAX_COST_USD（デフォルト2.5ドル）はハード制限であり、予算ではありません。より高いmax_cost_usdはそれに制限されるため、それ以上のコストが必要な実行は分割するか、オペレーターが上限を引き上げる必要があります。
4. 常に消費したものを報告する。 すべての完了した呼び出し（get_jobで収集したバックグラウンドジョブを含む）の後、ユーザーに報告する：モデル、cost_usd、トークン（prompt / cached / completion / reasoning）、さらにiterationsとstopped。コストがわずかであっても、また実行が失敗した場合や早期に停止した場合でも報告します。まだrunning状態のジョブにはコストがかかっていません — その旨を伝え、収集時に報告します。実際のコストが見積もりを約50%以上超えた場合は、それも伝えます。
reasoning_effort（low/medium/high、一部のモデルではnoneも）は呼び出しごとに設定され、APIに渡されます。モデルによってサポート状況は異なります（カタログには記載されていません）：一部のモデルは拒否し、他はnoneを拒否します。設定しない場合、flagshipモデルは自身の（高価な）デフォルトではなくlowで実行され、他のモデルは自身のデフォルトを使用します。モデルがパラメータを拒否した場合、サーバーはそのモデルのデフォルトをドロップします。深さが重要な場合は明示的に設定します（high）。明示的な値は常にそのまま送信され、拒否された場合はAPIエラーとして返されます。
| タスク | モデル |
|---|---|
| 簡単な質問、要約、抽出、分類 | リスト内の最も安価なモデル |
| コード生成 / リファクタリング | リストにあればコードモデル、なければ安価な汎用モデル |
| 深層分析、多段階推論、多数のファイルのレビュー | 最新のフラッグシップ（最も高いバージョン） |
| 入力が約200Kトークンを超える | コンテキストウィンドウが適合するモデル — ctxを確認 |
| 画像入力 | [images]とマークされたモデル |
| 画像生成 | 最も安価な画像モデルで反復し、最終レンダリングは高品質モデルで |
ツール → モデル クイックリファレンス
agent(prompt, model, tools?, image_paths?, system?, conversation?, file_paths?, reasoning_effort?, max_iterations?, max_seconds?, max_cost_usd?, background=False)
テキスト（および画像）をGrokに送信するための単一ツール。
| パラメータ | デフォルト | 備考 |
|---|---|---|
model | 必須 | モデルの選択を参照 |
tools | [] | Grokが自身で呼び出せるワークスペースツール：read、write、shell、fetch、search。未知の名前はエラーになります |
image_paths | — | プロンプトとともに送信されるローカル画像（モデルは[images]である必要あり）。サーバーから参照可能である必要があります — パスを参照 |
max_iterations | 100 | ツールループ内のモデルラウンド数（サーバー上限 — 下げることのみ可能） |
max_seconds | 1800 | 実行のウォールクロック予算（サーバー上限） |
max_cost_usd | 2.5 | 実行の推定USD予算（サーバー上限 — より高い値は制限される） |
conversation | —（ステートレス） | タスク名 "<プロジェクト>/<タスク>"（例："grok-mcp/security-audit"） — 1つのタスクの呼び出し間でコンテキストを保持。Grokはオンデマンドで履歴を取得します（get_recent_history/search_history）。新しいタスク → 新しい名前。1回限りの呼び出し → 省略（履歴は保持されません。バックグラウンドジョブは数日間結果を保持します）。プロジェクトプレフィックスは重要です：HTTP経由ではサーバーはプロジェクトを区別できません。200文字以下、制御文字なし |
file_paths | — | サーバー側で注入されるファイル内容（自分でファイルを選択） |
reasoning_effort | flagshipではlow、それ以外はモデルデフォルト | 呼び出しごとに設定。明示的な値はそのまま送信 |
background | False | 即座に{job_id}を返す。get_job(job_id)で収集。長時間実行に必須ではありません — 制限を参照 |
未知のパラメータは拒否され、有効なパラメータのリストが返されます。
戻り値（整形済みJSON）：
{
"answer": "...",
"model": "grok-4.3",
"reasoning_effort": "low",
"tokens": {"prompt": 6909, "cached": 576, "completion": 49, "reasoning": 141},
"cost_usd": 0.0085,
"tool_calls": [{"tool": "read", "args": {"path": "README.md"}, "result_chars": 22463}],
"iterations": 2,
"stopped": "answer",
"hint": "実行が早期に終了したか、フラッグシップで高コストだった場合のみ表示されます"
}
stoppedはループがどのように終了したかを示します：answer（正常）、max_iterations、context（ウィンドウがほぼ一杯）、loop（同じツール呼び出しが繰り返された）、time（max_seconds）、またはcost（max_cost_usd）。どの場合でも最後のラウンドはツールなしで実行されるため、answerにはGrokが収集した情報から結論付けられた内容が常に含まれます — 作業が破棄されることはありません。
制限（サーバー環境変数、デフォルト）
| 制限 | デフォルト | 環境変数 | 発生する動作 |
|---|---|---|---|
| フォアグラウンド呼び出し時間 | 60秒 | GROK_FOREGROUND_TIMEOUT | 呼び出しはバックグラウンドに移動：{job_id， status: "running", note}を受け取る — get_jobで収集。何も失われません。クライアントタイムアウトは発生しません |
| 実行時間 | 1800秒 | GROK_JOB_MAX_SECONDS / max_seconds | 最終回答、stopped: "time" |
| 実行コスト | 2.5ドル | GROK_MAX_COST_USD / max_cost_usd | 最終回答、stopped: "cost" |
| モデルラウンド数 | 100 | GROK_MAX_ITERATIONS / max_iterations | 最終回答、stopped: "max_iterations" |
| 入力（prompt + file_paths + images） | モデルのウィンドウの60% | GROK_INPUT_MAX_RATIO | API呼び出しの前に拒否、ウィンドウが適合するモデルを指定 |
| 1つのツール結果 | ウィンドウの15% | GROK_TOOL_RESULT_MAX_RATIO | Grokは代わりに「結果が大きすぎます — 行範囲またはgrepで読み取ってください」を受け取る |
| 会話全体 | ウィンドウの80% | GROK_CONTEXT_MAX_RATIO | 古い結果が一度トリミングされ、その後新しい結果が拒否され、stopped: "context" |
| シェルコマンド | 240秒 | GROK_SHELL_TIMEOUT | コマンドが強制終了され、エラーがGrokに返される |
パス
Docker設定では、サーバーはマウントされたディレクトリ（ワークスペースとASSETS_DIR）のみを参照します。image_paths、file_paths、およびGrokが読み取るパスはそこに存在する必要があります — ホストの/tmpやスクラッチパッドのパスは見えません。最初にファイルをワークスペースにコピーしてください。stdioサーバーは、ユーザーが見える範囲（GROK_READ_ALLOWED_PATHSが設定されている場合はそれに制限される）を参照します。サーバーが見られないパスは、参照可能なルートのリストとともに事前に拒否されます。
自動プロジェクトコンテキスト： サーバーがgitプロジェクト内で実行されている場合（stdio）、
agent()は検出された言語とフレームワークをシステムプロンプトの前に追加します。Docker設定では何も注入されません。systemがすでに[Project Context]で始まっている場合、注入はスキップされます。
Grokに自身のコンテキストを収集させます。 自分でファイルを読んでプロンプトに貼り付けないでください — tools=["read"]を渡し（git log/grep/テスト実行にはshellを追加）、何を見るかを説明してください。ファイル内容はあなたのコンテキストに入りません：
agent(prompt="src/grok_mcp/tools/agent.py と chat.py の重複ロジックをレビューしてください。",
model="<リストからフラッグシップ>", tools=["read", "shell"])
読み取り範囲を限定します。 プロンプトでファイル（または狭いディレクトリ）を指定してください — リポジトリ全体に対して「必要なものを読んでください」とすると、実行が170万トークンに達する可能性があります。大きなファイルの場合は、shell grep -nでコードの場所を特定させ、行範囲のみを読み取らせます（readにoffset/limitを使用）。
代わりに、どのファイルが重要かすでに正確にわかっている場合はfile_pathsを使用します（1ラウンドトリップ、ループなし）。
長時間実行とコスト。 各ラウンドで会話全体が再送信されます。xAIは変更されていないプレフィックスを自動的にキャッシュします（tokens.cached、約75%割引で課金）。そのため、ラウンドは主に新しい部分のコストを支払います。古い結果をトリミングすると、1回のキャッシュミスが発生します。3回目の同一のツール呼び出しは拒否され、5回目でループが終了します。長時間の呼び出しは60秒後に単に{job_id}として返されます — その後get_jobをポーリングします。background=Trueは最初の1分間の待機をスキップするだけです。
画像。 agent(prompt="このスクリーンショットは何を示していますか？", model=...， image_paths=["<workspace>/shot.png"]) — ファイルはサーバーが見るディレクトリに存在する必要があります（パスを参照）。呼び出しごとに1つの具体的な質問をします。画像をコードと比較する必要がある場合は、toolsと組み合わせます。
generate_image(prompt, output_path, model, aspect_ratio?, resolution?, ref_image_paths?)
modelは必須です — ツールの説明には、画像モデルと画像あたりの価格がリストされています。
コスト規律：
- プロンプトが適切になるまで最も安価な画像モデルで反復し、最終レンダリングのためだけに高品質モデルに切り替えます。
- 戻り値：
{path， model, prompt， format}。
output_pathは絶対パスである必要があります。親ディレクトリは自動的に作成されます。
参照画像付き（品質層モデルの方がスタイル転送に優れています）：
- 既存の画像とのスタイルの一貫性が重要な場合、
ref_image_pathsを渡します。最大3つの絶対パスを順番に受け取ります。プロンプトはそれらを位置的に参照できます（例：「最初からジオメトリ、2番目からエッジキャラクター」）。渡したすべてのパスが転送され、何も黙って破棄されることはありません。 - モデルごとの上限（現在の画像モデルでは3）はxAIによって強制され、それを超えるとそのメッセージがそのまま表示されます。
- 参照ファイルはマジックバイトからMIMEタイプが推測されるため、以前の結果は保存された拡張子に関係なく、そのまま参照として再入力できます。
aspect_ratio（デフォルト"1:1"）とresolution（デフォルト"1k"、"2k"も可）は参照なしの場合と同様に適用されます。出力は参照画像の縦横比を継承しません — 16:10の参照でも、特に指定しない限り正方形が生成されます。したがって、1kの正方形以上のものが必要な場合は、必ず両方を明示的に指定してください。
コスト比較：現在のモデルとGrok
現在のモデルの正確な価格については、プロバイダーの現在の価格表を確認してください。