콘텐츠로 이동

모델 컨텍스트 프로토콜 (MCP)

Model Context Protocol (MCP)은 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP 문서에서는 다음과 같이 설명합니다.

MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI 애플리케이션용 USB-C 포트라고 생각하면 됩니다. USB-C가 기기를 다양한 주변 기기와 액세서리에 연결하는 표준화된 방법을 제공하듯이, MCP는 AI 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방법을 제공합니다.

이 SDK는 세 가지 유형의 MCP 서버를 지원합니다.

  1. 호스티드 MCP 서버 도구 – OpenAI Responses API에서 도구로 사용하는 원격 MCP 서버
  2. Streamable HTTP MCP 서버 – Streamable HTTP 전송 방식을 구현하는 로컬 또는 원격 서버
  3. Stdio MCP 서버 – 표준 입출력을 통해 접근하는 서버(가장 간단한 옵션)

참고: SDK에는 레거시 서버 전송 이벤트(Server‑Sent Events) 전송 방식을 위한 MCPServerSSE도 포함되어 있지만, MCP 프로젝트에서는 SSE가 사용 중단되었습니다. 새로운 연동에는 Streamable HTTP 또는 stdio를 우선 사용하세요.

사용 사례에 따라 서버 유형을 선택하세요.

필요한 기능권장 옵션
기본 OpenAI Responses 모델로 공개적으로 접근 가능한 원격 서버 호출1. 호스티드 MCP 도구
공개적으로 접근 가능한 원격 서버를 사용하되 도구 호출은 로컬에서 실행2. Streamable HTTP
로컬에서 실행 중인 Streamable HTTP 서버 사용2. Streamable HTTP
OpenAI Responses 이외의 모델로 Streamable HTTP 서버 사용2. Streamable HTTP
표준 입출력 프로토콜만 지원하는 로컬 MCP 서버 사용3. Stdio

Agents SDK는 내부적으로 MCP TypeScript SDK v2 클라이언트를 사용합니다. 그렇다고 해서 MCP 서버를 v2 서버 패키지로 마이그레이션할 필요는 없습니다. stdio 및 Streamable HTTP 연결에서는 Agents SDK가 프로토콜을 자동으로 협상하며, MCP TypeScript SDK v1으로 구현된 기존 서버가 호환되는 프로토콜 버전을 지원하는 경우 해당 서버와의 호환성을 유지합니다.

애플리케이션에서 Agents SDK의 MCPServerStdio, MCPServerStreamableHttp 또는 MCPServerSSE 클래스만 사용하는 경우, 이러한 호환성을 위해 MCP v1 및 v2 패키지를 설치하거나 둘 사이를 연결할 필요가 없습니다. v2 MCP SDK API를 도입하려는 경우 애플리케이션에서 직접 관리하는 MCP SDK 객체는 별도로 마이그레이션하세요. MCP TypeScript SDK의 v1에서 v2로의 마이그레이션 가이드를 참고하세요.

호스티드 툴은 전체 왕복 처리를 모델 측에서 수행하도록 합니다. 코드에서 MCP 서버를 호출하는 대신, OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델로 스트리밍합니다.

다음은 호스티드 MCP 도구를 사용하는 가장 간단한 예제입니다. 호스티드 MCP 서버 도구를 만드는 데 유용한 hostedMcpTool 유틸리티 함수에 원격 MCP 서버의 레이블과 URL을 전달할 수 있습니다.

hostedAgent.ts
import { Agent, hostedMcpTool } from '@openai/agents';
export const agent = new Agent({
name: 'MCP Assistant',
instructions: 'You must always use the MCP tools to answer questions.',
tools: [
hostedMcpTool({
serverLabel: 'deepwiki',
serverUrl: 'https://mcp.deepwiki.com/mcp',
}),
],
});

그런 다음 run 함수(또는 직접 사용자 지정한 Runner 인스턴스의 run 메서드)로 에이전트를 실행할 수 있습니다.

호스티드 MCP 도구로 실행
import { run } from '@openai/agents';
import { agent } from './hostedAgent';
async function main() {
const result = await run(
agent,
'Which language is the repo I pointed in the MCP tool settings written in?',
);
console.log(result.finalOutput);
}
main().catch(console.error);

MCP 결과를 점진적으로 스트리밍하려면 Agent를 실행할 때 stream: true를 전달하세요.

호스티드 MCP 도구로 실행(스트리밍)
import { isOpenAIResponsesRawModelStreamEvent, run } from '@openai/agents';
import { agent } from './hostedAgent';
async function main() {
const result = await run(
agent,
'Which language is the repo I pointed in the MCP tool settings written in?',
{ stream: true },
);
for await (const event of result) {
if (
isOpenAIResponsesRawModelStreamEvent(event) &&
event.data.event.type !== 'response.mcp_call_arguments.delta' &&
event.data.event.type !== 'response.output_text.delta'
) {
console.log(`Got event of type ${JSON.stringify(event.data)}`);
}
}
console.log(`Done streaming; final result: ${result.finalOutput}`);
}
main().catch(console.error);

민감한 작업의 경우 개별 도구 호출에 사람의 승인을 요구할 수 있습니다. requireApproval: 'always'를 전달하거나, 도구 이름을 'never'/'always'에 매핑하는 세분화된 설정 객체를 전달하세요.

도구 호출의 안전성을 프로그래밍 방식으로 판단할 수 있다면 onApproval 콜백을 사용하여 도구 호출을 승인하거나 거부할 수 있습니다. 사람의 승인이 필요한 경우에는 로컬 함수 도구와 마찬가지로 interruptions를 사용하는 휴먼 인 더 루프 (HITL) 방식을 사용할 수 있습니다.

호스티드 MCP 도구의 휴먼 인 더 루프 (HITL)
import { Agent, run, hostedMcpTool, RunToolApprovalItem } from '@openai/agents';
async function main(): Promise<void> {
const agent = new Agent({
name: 'MCP Assistant',
instructions: 'You must always use the MCP tools to answer questions.',
tools: [
hostedMcpTool({
serverLabel: 'deepwiki',
serverUrl: 'https://mcp.deepwiki.com/mcp',
// 'always' | 'never' | { never, always }
requireApproval: {
never: {
toolNames: ['read_wiki_structure', 'read_wiki_contents'],
},
always: {
toolNames: ['ask_question'],
},
},
}),
],
});
let result = await run(
agent,
'For the repository openai/codex, tell me the primary programming language.',
);
while (result.interruptions && result.interruptions.length) {
for (const interruption of result.interruptions) {
// Human in the loop here
const approval = await confirm(interruption);
if (approval) {
result.state.approve(interruption);
} else {
result.state.reject(interruption);
}
}
result = await run(agent, result.state);
}
console.log(result.finalOutput);
}
import { stdin, stdout } from 'node:process';
import * as readline from 'node:readline/promises';
async function confirm(item: RunToolApprovalItem): Promise<boolean> {
const rl = readline.createInterface({ input: stdin, output: stdout });
const name = item.name;
const params = item.arguments;
const answer = await rl.question(
`Approve running tool (mcp: ${name}, params: ${params})? (y/n) `,
);
rl.close();
return answer.toLowerCase().trim() === 'y';
}
main().catch(console.error);

hostedMcpTool(...)은 MCP 서버 URL과 커넥터 기반 서버를 모두 지원합니다.

옵션타입설명
serverLabelstring이벤트와 트레이스에서 호스티드 MCP 서버를 식별하는 필수 레이블입니다.
serverUrlstring원격 MCP 서버 URL입니다(일반 호스티드 MCP 서버에 사용).
connectorIdstringOpenAI 커넥터 ID입니다(커넥터 기반 호스티드 서버에서는 serverUrl 대신 사용).
authorizationstring호스티드 MCP 백엔드로 전송되는 선택적 인가 토큰입니다.
headersRecord<string, string>선택적 추가 요청 헤더입니다.
allowedToolsstring[] | object모델에 노출되는 도구 이름의 허용 목록입니다. string[] 또는 { toolNames?: string[] }를 전달하세요.
allowedCallers('direct' | 'programmatic')[]호스티드 MCP 도구를 직접 호출할지, 프로그래밍 방식 도구 호출을 통해 호출할지, 또는 두 방식 모두 허용할지를 제어하는 Responses 전용 목록입니다. 비어 있으면 안 됩니다.
deferLoadingboolean호스티드 MCP 도구의 Responses 전용 지연 로딩 설정입니다. 동일한 에이전트에 toolSearchTool()이 필요합니다.
requireApproval'never' | 'always' | object호스티드 MCP 도구 호출의 승인 정책입니다. 도구별로 재정의하려면 객체 형식을 사용하세요. 기본값은 'never'입니다.
onApproval승인 콜백requireApproval에서 승인 처리를 요구할 때 프로그래밍 방식으로 승인/거부하기 위한 선택적 콜백입니다.

호스티드 MCP 서버의 도구 정의를 처음부터 노출하는 대신 모델이 필요에 따라 도구 검색으로 로드하게 하려면 deferLoading: true를 설정하세요. 이 기능은 OpenAI Responses API에서만 작동하며, 동일한 요청에 toolSearchTool()이 필요하고, GPT-5.4 및 그 이후에 출시된 지원 모델과 함께 사용해야 합니다. 전체 지연 로딩 설정은 도구 가이드를 참고하세요.

호스티드 MCP 도구를 모델이 생성한 JavaScript에서만 호출해야 하는 경우 allowedCallers: ['programmatic']을 설정하고, 두 호출 경로를 모두 허용하려면 'direct'와 'programmatic'을 모두 포함하세요. 동일한 에이전트에 programmaticToolCallingTool()을 추가하세요. 프로그램이 MCP 도구를 호출할 때도 기존 requireApproval 및 onApproval 정책이 적용됩니다. 전체 설정은 프로그래밍 방식 도구 호출을 참고하세요.

requireApproval의 객체 형식에는 선택적으로 always 및 never 항목을 지정할 수 있습니다. 각 항목은 toolNames 또는 도구의 읽기 전용 어노테이션을 기준으로 도구를 선택할 수 있습니다. 선택적 onApproval 콜백은 현재 실행 컨텍스트와 승인 항목을 받은 다음, approve와 선택적 reason을 포함하는 프로미스를 반환합니다.

호스티드 MCP는 OpenAI 커넥터도 지원합니다. serverUrl을 제공하는 대신 커넥터의 connectorId와 authorization 토큰을 전달하세요. 그러면 Responses API가 인증을 처리하고 호스티드 MCP 인터페이스를 통해 커넥터의 도구를 노출합니다.

커넥터 기반 호스티드 MCP 도구
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',
}),
],
});

이 예제에서 GOOGLE_CALENDAR_AUTHORIZATION 환경 변수는 Google OAuth Playground에서 얻은 OAuth 토큰을 저장하며, 이 토큰은 커넥터 기반 서버에 Calendar API를 호출할 권한을 부여합니다. 스트리밍도 보여 주는 실행 가능한 코드 예제는 examples/connectors를 참고하세요.

완전히 작동하는 코드 예제(호스티드 툴/Streamable HTTP/stdio + 스트리밍, HITL, onApproval)는 GitHub 저장소의 examples/mcp에 있습니다.

전송 방식을 선택하는 것 외에도 Agent.mcpConfig를 설정하여 로컬 MCP 도구의 준비 방식을 조정할 수 있습니다.

에이전트의 로컬 MCP 도구 설정
import { Agent, MCPServerStreamableHttp } from '@openai/agents';
const server = new MCPServerStreamableHttp({
url: 'https://your-own-domain-here/mcp',
name: 'Docs server',
});
const agent = new Agent({
name: 'Assistant',
mcpServers: [server],
mcpConfig: {
// Try to convert MCP tool schemas to strict JSON schema.
convertSchemasToStrict: true,
// Set to null to raise MCP tool failures instead of returning model-visible error text.
errorFunction: null,
// Prefix local MCP tool names with their server name.
includeServerInToolNames: true,
},
});

참고 사항:

  • convertSchemasToStrict는 가능한 범위에서 변환을 시도합니다. 스키마를 변환할 수 없으면 원래 스키마를 사용합니다.
  • errorFunction은 MCP 도구 호출 실패를 모델에 전달하는 방식을 제어합니다.
  • errorFunction이 설정되지 않으면 SDK는 기본 도구 오류 포매터를 사용합니다.
  • 서버 수준의 errorFunction 값은 해당 서버에 대해 Agent.mcpConfig.errorFunction을 재정의합니다.
  • includeServerInToolNames는 명시적으로 활성화해야 합니다. 활성화하면 각 로컬 MCP 도구가 서버 접두사가 붙은 결정적 이름으로 모델에 노출되므로, 여러 MCP 서버가 같은 이름의 도구를 제공할 때 충돌을 방지하는 데 도움이 됩니다.
  • SDK는 URL에서 파생된 서버 이름과 전송 오류에서 URL 자격 증명, 쿼리 매개변수, 프래그먼트를 제거한 후 로그, 트레이스, 오류 메시지를 통해 노출합니다. 안정적인 서버 레이블이 필요하다면 비밀 정보가 포함되지 않은 고유한 name을 명시적으로 설정하세요.
  • 서로 다른 URL에서 파생된 서버 이름이 자격 증명, 쿼리 매개변수, 프래그먼트를 제거한 후 같아지고, 해당 서버들이 같은 이름의 도구를 제공한다면 모델 요청 전에 설정이 실패합니다. 해당 서버에 비밀 정보가 포함되지 않은 고유한 name 값을 명시적으로 설정하세요.

에이전트가 로컬 또는 원격 Streamable HTTP MCP 서버와 직접 통신하는 경우, 서버의 url, name 및 필요한 선택적 설정으로 MCPServerStreamableHttp를 인스턴스화하세요.

Streamable HTTP MCP 서버로 실행
import { Agent, run, MCPServerStreamableHttp } from '@openai/agents';
async function main() {
const mcpServer = new MCPServerStreamableHttp({
url: 'https://mcp.deepwiki.com/mcp',
name: 'DeepWiki MCP Server',
});
const agent = new Agent({
name: 'DeepWiki Assistant',
instructions: 'Use the tools to respond to user requests.',
mcpServers: [mcpServer],
});
try {
await mcpServer.connect();
const result = await run(
agent,
'For the repository openai/codex, tell me the primary programming language.',
);
console.log(result.finalOutput);
} finally {
await mcpServer.close();
}
}
main().catch(console.error);

생성자 옵션:

옵션타입설명
urlstringStreamable HTTP 서버 URL입니다.
namestring서버의 선택적 레이블입니다.
cacheToolsListboolean지연 시간을 줄이기 위해 도구 목록을 캐시합니다.
clientSessionTimeoutSecondsnumberMCP 클라이언트 세션의 타임아웃입니다.
toolFilterMCPToolFilterCallable | MCPToolFilterStatic사용 가능한 도구를 필터링합니다.
toolMetaResolverMCPToolMetaResolver호출별로 MCP _meta 요청 필드를 주입합니다.
toolInputGuardrailsToolInputGuardrailDefinition[]이 서버에서 변환된 도구를 호출할 때마다 호출 전에 이 가드레일을 실행합니다.
toolOutputGuardrailsToolOutputGuardrailDefinition[]이 서버에서 변환된 도구를 호출할 때마다 호출 후에 이 가드레일을 실행합니다.
useStructuredContentbooleanMCP structuredContent가 있고 결과가 오류가 아닌 경우, 이를 JSON으로 직렬화하여 모델에 표시되는 출력으로 사용합니다. 기본값은 false입니다.
customDataExtractorMCPToolCustomDataExtractor생성되는 로컬 MCP 도구 출력 항목에 SDK 전용 JSON 메타데이터를 첨부합니다. 콜백은 MCP 결과의 _meta, structuredContent, isError 및 모델에 표시되는 도구 출력을 읽을 수 있습니다.
errorFunctionMCPToolErrorFunction | nullMCP 호출 실패를 모델에 표시되는 텍스트로 매핑합니다.
timeoutnumber요청별 타임아웃(밀리초)입니다.
loggerLogger사용자 지정 로거입니다.
authProviderOAuthClientProviderMCP TypeScript SDK의 OAuth 제공자입니다.
requestInitRequestInit요청에 사용할 Fetch 초기화 옵션입니다.
fetchFetchLike사용자 지정 fetch 구현입니다.
reconnectionOptionsStreamableHTTPReconnectionOptions재연결 조정 옵션입니다.
sessionIdstringMCP 연결에 명시적으로 지정할 세션 ID입니다.

생성자는 authProvider, requestInit, fetch, reconnectionOptions, sessionId와 같은 추가 MCP TypeScript SDK 옵션도 받습니다. 자세한 내용은 MCP TypeScript SDK 저장소와 해당 문서를 참고하세요.

toolInputGuardrails와 toolOutputGuardrails는 SDK의 로컬 함수 도구 가드레일 파이프라인을 사용합니다. 스트리밍 실행과 비스트리밍 실행 모두에서 이 서버로부터 변환된 모든 도구에 적용됩니다. Responses API가 원격으로 실행하는 호스티드 MCP 도구에는 적용되지 않습니다. 거부 동작과 승인 순서는 도구 가드레일을 참고하세요.

표준 입출력만 제공하는 서버의 경우 fullCommand로 MCPServerStdio를 인스턴스화하세요.

Stdio MCP 서버로 실행
import { Agent, run, MCPServerStdio } from '@openai/agents';
import * as path from 'node:path';
async function main() {
const samplesDir = path.join(__dirname, 'sample_files');
const mcpServer = new MCPServerStdio({
name: 'Filesystem MCP Server, via local package',
fullCommand: `pnpm exec mcp-server-filesystem ${samplesDir}`,
});
await mcpServer.connect();
try {
const agent = new Agent({
name: 'FS MCP Assistant',
instructions:
'Use the tools to read the filesystem and answer questions based on those files. If you are unable to find any files, you can say so instead of assuming they exist.',
mcpServers: [mcpServer],
});
const result = await run(agent, 'Read the files and list them.');
console.log(result.finalOutput);
} finally {
await mcpServer.close();
}
}
main().catch(console.error);

생성자 옵션:

옵션타입설명
command / argsstring / string[]stdio 서버용 명령어 + 인수입니다.
fullCommandstringcommand + args를 대체하는 전체 명령어 문자열입니다.
envRecord<string, string>서버 프로세스의 환경 변수입니다.
cwdstring서버 프로세스의 작업 디렉터리입니다.
cacheToolsListboolean지연 시간을 줄이기 위해 도구 목록을 캐시합니다.
clientSessionTimeoutSecondsnumberMCP 클라이언트 세션의 타임아웃입니다.
namestring서버의 선택적 레이블입니다.
encodingstringstdio 스트림의 인코딩입니다.
encodingErrorHandler'strict' | 'ignore' | 'replace'인코딩 오류 처리 전략입니다.
toolFilterMCPToolFilterCallable | MCPToolFilterStatic사용 가능한 도구를 필터링합니다.
toolMetaResolverMCPToolMetaResolver호출별로 MCP _meta 요청 필드를 주입합니다.
toolInputGuardrailsToolInputGuardrailDefinition[]이 서버에서 변환된 도구를 호출할 때마다 호출 전에 이 가드레일을 실행합니다.
toolOutputGuardrailsToolOutputGuardrailDefinition[]이 서버에서 변환된 도구를 호출할 때마다 호출 후에 이 가드레일을 실행합니다.
useStructuredContentbooleanMCP structuredContent가 있고 결과가 오류가 아닌 경우, 이를 JSON으로 직렬화하여 모델에 표시되는 출력으로 사용합니다. 기본값은 false입니다.
customDataExtractorMCPToolCustomDataExtractor생성되는 로컬 MCP 도구 출력 항목에 SDK 전용 JSON 메타데이터를 첨부합니다. 콜백은 MCP 결과의 _meta, structuredContent, isError 및 모델에 표시되는 도구 출력을 읽을 수 있습니다.
errorFunctionMCPToolErrorFunction | nullMCP 호출 실패를 모델에 표시되는 텍스트로 매핑합니다.
timeoutnumber요청별 타임아웃(밀리초)입니다.
loggerLogger사용자 지정 로거입니다.

여러 MCP 서버를 사용하는 경우 connectMcpServers를 사용하여 한곳에서 서버들을 연결하고, 실패를 추적하고, 연결을 종료할 수 있습니다. 이 헬퍼는 active, failed, errors 컬렉션이 있는 MCPServers 인스턴스를 반환하므로 정상적인 서버만 에이전트에 전달할 수 있습니다.

여러 MCP 서버 관리
import {
Agent,
MCPServerStreamableHttp,
connectMcpServers,
run,
} from '@openai/agents';
async function main() {
const servers = [
new MCPServerStreamableHttp({
url: 'https://mcp.deepwiki.com/mcp',
name: 'DeepWiki MCP Server',
}),
new MCPServerStreamableHttp({
url: 'http://localhost:8001/mcp',
name: 'Local MCP Server',
}),
];
const mcpServers = await connectMcpServers(servers, {
connectInParallel: true,
});
try {
console.log(`Active servers: ${mcpServers.active.length}`);
console.log(`Failed servers: ${mcpServers.failed.length}`);
for (const [server, error] of mcpServers.errors) {
console.warn(`${server.name} failed to connect: ${error.message}`);
}
const agent = new Agent({
name: 'MCP lifecycle agent',
instructions: 'Use MCP tools to answer user questions.',
mcpServers: mcpServers.active,
});
const result = await run(
agent,
'Which language is the openai/codex repository written in?',
);
console.log(result.finalOutput);
} finally {
await mcpServers.close();
}
}
main().catch(console.error);

사용 사례:

  • 여러 서버를 한 번에 연결: 모든 서버에 병렬로 연결하고 에이전트에 mcpServers.active를 사용합니다.
  • 부분 실패 처리: failed + errors를 확인하고 계속 진행할지 재시도할지 결정합니다.
  • 실패한 서버 재시도: mcpServers.reconnect()를 호출합니다(기본적으로 실패한 서버만 재시도).

엄격한 “전체 성공 또는 전체 실패” 방식의 연결이나 다른 타임아웃이 필요하다면 connectMcpServers(servers, options)를 사용하고 환경에 맞게 옵션을 조정하세요.

connectMcpServers 옵션:

옵션타입기본값설명
connectTimeoutMsnumber | null10000각 서버의 connect() 타임아웃입니다. 비활성화하려면 null을 사용하세요.
closeTimeoutMsnumber | null10000각 서버의 close() 타임아웃입니다. 비활성화하려면 null을 사용하세요.
dropFailedbooleantrue실패한 서버를 active에서 제외합니다.
strictbooleanfalse서버가 하나라도 연결에 실패하면 예외를 발생시킵니다.
suppressAbortErrorbooleantrue중단 유형의 오류는 무시하되 실패한 서버는 계속 추적합니다.
connectInParallelbooleanfalse모든 서버에 순차적으로 연결하는 대신 동시에 연결합니다.

mcpServers.reconnect(options)는 다음을 지원합니다.

옵션타입기본값설명
failedOnlybooleantrue실패한 서버만 재시도하거나(true) 모든 서버에 다시 연결합니다(false).

다시 연결하기 전에 MCPServers는 선택된 서버의 연결을 종료합니다. 연결이 성공적으로 종료된 서버에만 다시 연결하며, 정리 작업의 실패 정보는 failed와 errors를 통해 계속 확인할 수 있습니다.

런타임이 Symbol.asyncDispose를 지원한다면 MCPServers에서 await using 패턴도 사용할 수 있습니다. TypeScript에서는 tsconfig.json에서 esnext.disposable을 활성화하세요.

{
"compilerOptions": {
"lib": ["ES2018", "DOM", "esnext.disposable"]
}
}

그런 다음 다음과 같이 작성할 수 있습니다.

비동기 리소스 해제로 연결된 MCP 서버 종료
import { MCPServerStreamableHttp, connectMcpServers } from '@openai/agents';
async function main() {
const servers = [
new MCPServerStreamableHttp({
url: 'https://your-own-domain-here/mcp',
name: 'Docs server',
}),
];
await using mcpServers = await connectMcpServers(servers);
}
main().catch(console.error);

Streamable HTTP 및 Stdio 서버의 경우 Agent가 실행될 때마다 사용 가능한 도구를 찾기 위해 list_tools()를 호출할 수 있습니다. 이러한 왕복 통신은 특히 원격 서버에서 지연 시간을 늘릴 수 있으므로, MCPServerStdio 또는 MCPServerStreamableHttp에 cacheToolsList: true를 전달하여 결과를 메모리에 캐시할 수 있습니다.

도구 목록이 바뀌지 않을 것이라고 확신하는 경우에만 이 기능을 활성화하세요. 나중에 캐시를 무효화하려면 서버 인스턴스에서 invalidateToolsCache()를 호출하세요. getAllMcpTools(...)를 통해 공유 MCP 도구 캐싱을 사용하는 경우 invalidateServerToolsCache(serverName)으로 서버 이름을 지정하여 무효화할 수도 있습니다.

고급 사용 사례에서는 getAllMcpTools({ generateMCPToolCacheKey })로 캐시 분할 방식을 사용자 지정할 수 있습니다(예: 서버 + 에이전트 + 실행 컨텍스트 기준).

기본적으로 로컬 MCP 도구는 MCP 서버가 제공하는 도구 이름을 그대로 유지합니다. 두 로컬 MCP 서버가 같은 이름의 도구를 노출하면 모델이 둘 중 하나를 안전하게 선택할 수 없으므로 SDK에서 도구 이름 중복 오류가 발생합니다.

서버 접두사가 붙은 결정적 이름을 사용하려면 에이전트에 mcpConfig.includeServerInToolNames: true를 설정하세요.

로컬 MCP 도구 이름에 서버 이름 접두사 추가
import { Agent, MCPServerStreamableHttp } from '@openai/agents';
const docsServer = new MCPServerStreamableHttp({
url: 'https://your-own-domain-here/docs/mcp',
name: 'docs',
});
const calendarServer = new MCPServerStreamableHttp({
url: 'https://your-own-domain-here/calendar/mcp',
name: 'calendar',
});
const agent = new Agent({
name: 'Assistant',
mcpServers: [docsServer, calendarServer],
mcpConfig: {
includeServerInToolNames: true,
},
});

이 설정을 사용하면 docs 서버의 search 도구는 모델에 mcp_docs__search로 노출되고, calendar 서버의 search 도구는 mcp_calendar__search로 노출됩니다. SDK는 여전히 원래 서버에서 원래 MCP 도구 이름으로 호출합니다.

생성된 이름은 ASCII에 안전한 문자로 구성되며, FunctionTool 인스턴스의 이름 길이 제한을 준수하고, 같은 에이전트의 로컬 FunctionTool 인스턴스나 활성화된 핸드오프의 이름과 충돌하지 않습니다. 이 설정은 Streamable HTTP, SSE, stdio를 비롯한 모든 로컬 MCP 전송 방식에 적용됩니다. 호스티드 MCP 도구는 기존 호스티드 서버 레이블과 도구 메타데이터를 유지합니다.

createMCPToolStaticFilter를 통한 정적 필터나 사용자 지정 함수를 전달하여 각 서버에서 노출되는 도구를 제한할 수 있습니다. 다음은 두 방식을 함께 보여 주는 예제입니다.

도구 필터링
import {
MCPServerStdio,
MCPServerStreamableHttp,
createMCPToolStaticFilter,
MCPToolFilterContext,
} from '@openai/agents';
interface ToolFilterContext {
allowAll: boolean;
}
const server = new MCPServerStdio({
fullCommand: 'my-server',
toolFilter: createMCPToolStaticFilter({
allowed: ['safe_tool'],
blocked: ['danger_tool'],
}),
});
const dynamicServer = new MCPServerStreamableHttp({
url: 'http://localhost:3000',
toolFilter: async ({ runContext }: MCPToolFilterContext, tool) =>
(runContext.context as ToolFilterContext).allowAll || tool.name !== 'admin',
});