From 6cf0c2ff4fcb9c2f3838938b147a41014f110523 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Mon, 8 Sep 2025 19:09:10 +0900 Subject: [PATCH] docs: explain hosted mcp connectors --- docs/src/content/docs/guides/mcp.mdx | 19 ++++++++++++++----- docs/src/content/docs/ja/guides/mcp.mdx | 13 +++++++++++++ examples/docs/mcp/hostedConnector.ts | 17 +++++++++++++++++ 3 files changed, 44 insertions(+), 5 deletions(-) create mode 100644 examples/docs/mcp/hostedConnector.ts diff --git a/docs/src/content/docs/guides/mcp.mdx b/docs/src/content/docs/guides/mcp.mdx index 05b4f092..616e8322 100644 --- a/docs/src/content/docs/guides/mcp.mdx +++ b/docs/src/content/docs/guides/mcp.mdx @@ -8,6 +8,7 @@ import hostedAgentExample from '../../../../../examples/docs/mcp/hostedAgent.ts? import hostedExample from '../../../../../examples/docs/mcp/hosted.ts?raw'; import hostedStreamExample from '../../../../../examples/docs/mcp/hostedStream.ts?raw'; import hostedHITLExample from '../../../../../examples/docs/mcp/hostedHITL.ts?raw'; +import hostedConnectorExample from '../../../../../examples/docs/mcp/hostedConnector.ts?raw'; import streamableHttpExample from '../../../../../examples/docs/mcp/streamableHttp.ts?raw'; import stdioExample from '../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../examples/docs/mcp/tool-filter.ts?raw'; @@ -68,6 +69,18 @@ If you can programmatically determine whether a tool call is safe, you can use t title="Human in the loop with hosted MCP tools" /> +### Connector-backed hosted servers + +Hosted MCP also supports OpenAI connectors. Instead of providing a `serverUrl`, pass the connector's `connectorId` and an `authorization` token. The Responses API then handles authentication and exposes the connector's tools through the hosted MCP interface. + + + +In this example the `GOOGLE_CALENDAR_AUTHORIZATION` environment variable holds an OAuth token obtained from the Google OAuth Playground, which authorizes the connector-backed server to call the Calendar API. For a runnable sample that also demonstrates streaming, see [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors). + Fully working samples (Hosted tools/Streamable HTTP/stdio + Streaming, HITL, onApproval) are [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) in our GitHub repository. ## 2. Streamable HTTP MCP servers @@ -102,11 +115,7 @@ Only enable this if you're confident the tool list won't change. To invalidate t You can restrict which tools are exposed from each server by passing either a static filter via `createMCPToolStaticFilter` or a custom function. Here’s a combined example showing both approaches: - + ## Further reading diff --git a/docs/src/content/docs/ja/guides/mcp.mdx b/docs/src/content/docs/ja/guides/mcp.mdx index 2a06d1c4..d77d292b 100644 --- a/docs/src/content/docs/ja/guides/mcp.mdx +++ b/docs/src/content/docs/ja/guides/mcp.mdx @@ -8,6 +8,7 @@ import hostedAgentExample from '../../../../../../examples/docs/mcp/hostedAgent. import hostedExample from '../../../../../../examples/docs/mcp/hosted.ts?raw'; import hostedStreamExample from '../../../../../../examples/docs/mcp/hostedStream.ts?raw'; import hostedHITLExample from '../../../../../../examples/docs/mcp/hostedHITL.ts?raw'; +import hostedConnectorExample from '../../../../../../examples/docs/mcp/hostedConnector.ts?raw'; import streamableHttpExample from '../../../../../../examples/docs/mcp/streamableHttp.ts?raw'; import stdioExample from '../../../../../../examples/docs/mcp/stdio.ts?raw'; import toolFilterExample from '../../../../../../examples/docs/mcp/tool-filter.ts?raw'; @@ -68,6 +69,18 @@ Hosted ツールは、往復の処理全体をモデル側に任せます。あ title="Human in the loop with hosted MCP tools" /> +### コネクター対応の Hosted サーバー + +Hosted MCP は OpenAI コネクターにも対応しています。`serverUrl` の代わりにコネクターの `connectorId` と `authorization` トークンを指定すると、Responses API が認証を処理し、コネクターが公開するツールを hosted MCP インターフェース経由で利用できます。 + + + +この例では、`GOOGLE_CALENDAR_AUTHORIZATION` 環境変数に Google OAuth Playground で取得した OAuth トークンを保存し、コネクター経由で Calendar API を呼び出しています。ストリーミングを含む実行可能なサンプルは [`examples/connectors`](https://github.com/openai/openai-agents-js/tree/main/examples/connectors) を参照してください。 + 完全に動作するサンプル（Hosted ツール/Streamable HTTP/stdio + Streaming、HITL、onApproval）は、GitHub リポジトリの [examples/mcp](https://github.com/openai/openai-agents-js/tree/main/examples/mcp) にあります。 ## 2. Streamable HTTP MCP servers diff --git a/examples/docs/mcp/hostedConnector.ts b/examples/docs/mcp/hostedConnector.ts new file mode 100644 index 00000000..aafb30c2 --- /dev/null +++ b/examples/docs/mcp/hostedConnector.ts @@ -0,0 +1,17 @@ +import { Agent, hostedMcpTool } from '@openai/agents'; + +const authorization = process.env.GOOGLE_CALENDAR_AUTHORIZATION!; + +export const connectorAgent = new Agent({ + name: 'Calendar Assistant', + instructions: + "You are a helpful assistant that can answer questions about the user's calendar.", + tools: [ + hostedMcpTool({ + serverLabel: 'google_calendar', + connectorId: 'connector_googlecalendar', + authorization, + requireApproval: 'never', + }), + ], +});