Skip to content

Commit 8360b32

Browse files
dkundel-openaidkundel-openai
committed
slight copy changes
1 parent 78823df commit 8360b32

File tree

2 files changed

+41
-37
lines changed

2 files changed

+41
-37
lines changed

‎docs/src/content/docs/guides/mcp.mdx‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@ There are three types of MCP servers this SDK supports:
2525

2626
Choose a server type based on your use‑case:
2727

28-
| What you need | Recommended option |
29-
| ----------------------------------------------------------------------- | ----------------------- |
30-
| Call publicly accessible remote servers within Responses API calls | **1. Hosted MCP tools** |
31-
| Use publicly accessible remote servers as an Agent's function tools | **2. Streamable HTTP** |
32-
| Use locally running Streamable HTTP servers | **2. Streamable HTTP** |
33-
| Use any Streamable HTTP servers with Chat-Completions-compatible models | **2. Streamable HTTP** |
34-
| Work with local MCP servers that only support the standard-I/O protocol | **3. Stdio** |
28+
| What you need | Recommended option |
29+
| -------------------------------------------------------------------------------- | ----------------------- |
30+
| Call publicly accessible remote servers with default OpenAI responses models | **1. Hosted MCP tools** |
31+
| Use publicly accessible remote servers but have the tool calls triggered locally | **2. Streamable HTTP** |
32+
| Use locally running Streamable HTTP servers | **2. Streamable HTTP** |
33+
| Use any Streamable HTTP servers with non-OpenAI Responses models | **2. Streamable HTTP** |
34+
| Work with local MCP servers that only support the standard-I/O protocol | **3. Stdio** |
3535

3636
## 1. Hosted MCP server tools
3737

@@ -61,15 +61,17 @@ To stream incremental MCP results, pass `stream: true` when you run the `Agent`:
6161

6262
#### Optional approval flow
6363

64-
For sensitive operations you can require human approval of individual tool calls. Pass either `requireApproval: 'always'` or a fine‑grained object mapping tool names to `'never'`/`'always'`:
64+
For sensitive operations you can require human approval of individual tool calls. Pass either `requireApproval: 'always'` or a fine‑grained object mapping tool names to `'never'`/`'always'`.
65+
66+
If you can programatically determine whether a tool call is safe, you can use the [`onApproval` callback](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) to approve or reject the tool call. If you require human approval, you can use the same [human-in-the-loop (HITL) approach](/openai-agents-js/guides/human-in-the-loop/) using `interruptions` as for local function tools.
6567

6668
<Code
6769
lang="typescript"
6870
code={hostedHITLExample}
6971
title="Human in the loop with hosted MCP tools"
7072
/>
7173

72-
Fully worked samples (streaming, approval, HITL) are [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) in our GitHub repository.
74+
Fully working samples (streaming, approval, HITL) are [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) in our GitHub repository.
7375

7476
## 2. Streamable HTTP MCP servers
7577

‎docs/src/content/docs/ja/guides/mcp.mdx‎

Lines changed: 30 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -13,93 +13,95 @@ import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw';
1313

1414
## 概要
1515

16-
[ **Model Context Protocol ( MCP )** ](https://modelcontextprotocol.io) は、アプリケーションが LLMs にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP のドキュメントより引用します。
16+
[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) は、アプリケーションが LLM にツールとコンテキストを提供する方法を標準化するオープンプロトコルです。MCP ドキュメントより引用します。
1717

18-
> MCP はアプリケーションが LLMs にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP を AI アプリケーションの USB-C ポートのようなものと考えてください。USB-C がデバイスをさまざまな周辺機器へ接続する標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールへ接続する標準化された方法を提供します。
18+
> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB-C ポートのようなものと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルをさまざまなデータソースやツールに接続するための標準化された方法を提供します。
1919
20-
この SDK がサポートする MCP サーバーは 3 種類あります。
20+
この SDK がサポートする MCP サーバーには次の 3 種類があります。
2121

22-
1. **ホスト型 MCP サーバーツール** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) でツールとして利用されるリモート MCP サーバー
23-
2. **Streamable HTTP MCP サーバー** – [Streamable HTTP トランスポート](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装したローカルまたはリモートサーバー
24-
3. **Stdio MCP サーバー** – 標準入出力経由でアクセスするサーバー（最もシンプルな選択肢）
22+
1. **Hosted MCP-server tools** – [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp) によりツールとして呼び出されるリモート MCP サーバー
23+
2. **Streamable HTTP MCP サーバー** – [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http) を実装したローカルまたはリモートサーバー
24+
3. **Stdio MCP サーバー** – 標準入力/出力経由でアクセスするサーバー（もっともシンプル）
2525

2626
ユースケースに応じてサーバータイプを選択してください。
2727

28-
| 必要なこと | 推奨オプション |
29-
| ---------------------------------------------------------------------- | -------------------------- |
30-
| Responses API の呼び出し内で公開リモートサーバーを呼び出す | **1. ホスト型 MCP ツール** |
31-
| エージェントの function tools として公開リモートサーバーを使用する | **2. Streamable HTTP** |
32-
| ローカルで動作する Streamable HTTP サーバーを使用する | **2. Streamable HTTP** |
33-
| Chat-Completions 互換モデルで任意の Streamable HTTP サーバーを使用する | **2. Streamable HTTP** |
34-
| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーと連携する | **3. Stdio** |
28+
| 必要なこと | 推奨オプション |
29+
| ---------------------------------------------------------------------------------------- | ----------------------- |
30+
| 公開アクセス可能なリモートサーバーを、デフォルトの OpenAI Responses モデルで呼び出したい | **1. Hosted MCP tools** |
31+
| 公開アクセス可能なリモートサーバーを使用しつつ、ツール呼び出しをローカルでトリガーしたい | **2. Streamable HTTP** |
32+
| ローカルで動作する Streamable HTTP サーバーを使用したい | **2. Streamable HTTP** |
33+
| OpenAI 以外の Responses モデルと組み合わせて任意の Streamable HTTP サーバーを使いたい | **2. Streamable HTTP** |
34+
| 標準 I/O プロトコルのみをサポートするローカル MCP サーバーと連携したい | **3. Stdio** |
3535

36-
## 1. ホスト型 MCP サーバーツール
36+
## 1. Hosted MCP サーバーツール
3737

38-
ホスト型ツールでは、往復処理全体がモデル内で行われます。コードが MCP サーバーを呼び出すかわりに、OpenAI Responses API がリモートツールのエンドポイントを呼び出し、その結果をストリームでモデルに返します。
38+
Hosted tool では、往復すべてがモデル内部で完結します。あなたのコードが MCP サーバーを呼び出す代わりに、OpenAI Responses API がリモートツールのエンドポイントを呼び出し、その結果をストリームでモデルに返します。
3939

4040
### クイックスタート
4141

42-
ホスト型 MCP ツールを使用する最もシンプルな例です。リモート MCP サーバーのラベルと URL を `hostedMcpTool` ユーティリティ関数に渡すことで、ホスト型 MCP サーバーツールを簡単に作成できます。
42+
Hosted MCP サーバーツールを使うもっともシンプルな例を示します。`hostedMcpTool` ユーティリティ関数にリモート MCP サーバーのラベルと URL を渡すだけで作成できます。
4343

4444
<Code lang="typescript" code={hostedAgentExample} title="hostedAgent.ts" />
4545

46-
次に、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行します。
46+
続いて、`run` 関数（またはカスタマイズした `Runner` インスタンスの `run` メソッド）でエージェントを実行します。
4747

4848
<Code
4949
lang="typescript"
5050
code={hostedExample}
5151
title="Run with hosted MCP tools"
5252
/>
5353

54-
インクリメンタルな MCP 実行結果をストリームで受け取るには、`Agent` を実行する際に `stream: true` を指定します。
54+
MCP の増分結果をストリーミングする場合は、`Agent` を実行するときに `stream: true` を渡してください。
5555

5656
<Code
5757
lang="typescript"
5858
code={hostedStreamExample}
5959
title="Run with hosted MCP tools (streaming)"
6060
/>
6161

62-
#### 任意の承認フロー
62+
#### オプションの承認フロー
6363

64-
機密性の高い操作では、個々のツール呼び出しに対して人間による承認を要求できます。`requireApproval: 'always'` もしくはツール名を `'never'` / `'always'` にマッピングした詳細オブジェクトを渡してください。
64+
機微な操作の場合、個々のツール呼び出しに人間の承認を必須にできます。`requireApproval: 'always'` を渡すか、ツール名ごとに `'never'` / `'always'` を指定するオブジェクトを渡してください。
65+
66+
ツール呼び出しが安全かどうかをプログラム的に判断できる場合は、[`onApproval` コールバック](https://github.com/openai/openai-agents-js/blob/main/examples/mcp/hosted-mcp-on-approval.ts) を使って承認または拒否できます。人間の承認が必要な場合は、ローカルの関数ツールと同様に `interruptions` を使用した [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop/) のアプローチが利用できます。
6567

6668
<Code
6769
lang="typescript"
6870
code={hostedHITLExample}
6971
title="Human in the loop with hosted MCP tools"
7072
/>
7173

72-
完全なサンプル（ストリーミング、承認、HITL）は GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。
74+
ストリーミング、承認、HITL を含む完全な動作例は GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。
7375

7476
## 2. Streamable HTTP MCP サーバー
7577

76-
エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーへ直接アクセスする場合は、サーバーの `url`、`name` と任意の設定を指定して `MCPServerStreamableHttp` をインスタンス化します。
78+
エージェントがローカルまたはリモートの Streamable HTTP MCP サーバーと直接通信する場合は、サーバーの `url`、`name`、オプション設定を指定して `MCPServerStreamableHttp` を生成します。
7779

7880
<Code
7981
lang="typescript"
8082
code={streamableHttpExample}
8183
title="Run with Streamable HTTP MCP servers"
8284
/>
8385

84-
コンストラクターでは `authProvider`、`requestInit`、`reconnectionOptions`、`sessionId` など、MCP TypeScript-SDK の追加オプションも利用できます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントを参照してください。
86+
コンストラクターでは `authProvider`, `requestInit`, `reconnectionOptions`, `sessionId` など、MCP TypeScript SDK の追加オプションも指定できます。詳細は [MCP TypeScript SDK リポジトリ](https://github.com/modelcontextprotocol/typescript-sdk) とそのドキュメントをご覧ください。
8587

8688
## 3. Stdio MCP サーバー
8789

88-
標準 I/O のみを公開しているサーバーでは、`fullCommand` を指定して `MCPServerStdio` をインスタンス化します。
90+
標準 I/O のみを公開するサーバーには、`fullCommand` を指定して `MCPServerStdio` を生成します。
8991

9092
<Code
9193
lang="typescript"
9294
code={stdioExample}
9395
title="Run with Stdio MCP servers"
9496
/>
9597

96-
## 知っておくべきこと
98+
## 知っておくべきその他のポイント
9799

98-
**Streamable HTTP** と **Stdio** サーバーの場合、`Agent` を実行するたびに `list_tools()` を呼び出して利用可能なツールを取得することがあります。特にリモートサーバーではこの往復がレイテンシを増やすため、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して結果をメモリにキャッシュできます。
100+
**Streamable HTTP** および **Stdio** サーバーの場合、`Agent` は実行のたびに利用可能なツールを確認するため `list_tools()` を呼び出すことがあります。この往復は、特にリモートサーバーではレイテンシーを増やす可能性があります。ツールリストが変わらないと確信できる場合は、`MCPServerStdio` または `MCPServerStreamableHttp` に `cacheToolsList: true` を渡して結果をメモリにキャッシュできます。
99101

100-
ツールリストが変更されないと確信できる場合のみ有効にしてください。後でキャッシュを無効化するには、サーバーインスタンスの `invalidateToolsCache()` を呼び出します。
102+
後からキャッシュを無効化したい場合は、サーバーインスタンスの `invalidateToolsCache()` を呼び出してください。
101103

102-
## 参考資料
104+
## 参考文献
103105

104106
- [Model Context Protocol](https://modelcontextprotocol.io/) – 公式仕様
105107
- [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) – 上記で参照した実行可能デモ

0 commit comments

Comments
 (0)