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

Model Context Protocol (MCP)는 애플리케이션이 LLM에 도구와 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 문서에서 발췌:

MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB‑C 포트라고 생각하세요. USB‑C가 여러 주변기기와 액세서리에 장치를 연결하는 표준화된 방식을 제공하듯, MCP는 AI 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방식을 제공합니다.

이 SDK가 지원하는 MCP 서버 유형은 세 가지입니다:

호스티드 MCP 서버 도구 – OpenAI Responses API가 도구로 사용하는 원격 MCP 서버
Streamable HTTP MCP 서버 – Streamable HTTP transport를 구현한 로컬 또는 원격 서버
Stdio MCP 서버 – 표준 입출력으로 접근하는 서버(가장 단순한 옵션)

참고: SDK에는 레거시 Server‑Sent Events 전송용 MCPServerSSE도 포함되어 있지만, SSE는 MCP 프로젝트에서 더 이상 사용되지 않습니다. 신규 통합에는 Streamable HTTP 또는 stdio를 권장합니다.

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

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

1. 호스티드 MCP 서버 도구

호스티드 툴은 전체 라운드트립을 모델 내부로 밀어 넣습니다. 코드가 MCP 서버를 호출하는 대신, OpenAI Responses API가 원격 도구 엔드포인트를 호출하고 결과를 모델에 스트리밍합니다.

다음은 호스티드 MCP 도구를 사용하는 가장 간단한 예시입니다. 원격 MCP 서버의 라벨과 URL을 hostedMcpTool 유틸리티 함수에 전달하면 호스티드 MCP 서버 도구를 만드는 데 유용합니다.

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: 'gitmcp',
      serverUrl: 'https://gitmcp.io/openai/codex',
    }),
  ],
});

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

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를 전달하세요:

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?',
    { stream: true },
  );

  for await (const event of result) {
    if (
      event.type === 'raw_model_stream_event' &&
      event.data.type === 'model' &&
      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) 접근 방식을 사용할 수 있습니다.

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: 'gitmcp',
        serverUrl: 'https://gitmcp.io/openai/codex',
        // 'always' | 'never' | { never, always }
        requireApproval: {
          never: {
            toolNames: ['search_codex_code', 'fetch_codex_documentation'],
          },
          always: {
            toolNames: ['fetch_generic_url_content'],
          },
        },
      }),
    ],
  });

  let result = await run(agent, 'Which language is this repo written in?');
  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);

커넥터 기반 호스티드 서버

호스티드 MCP는 OpenAI 커넥터도 지원합니다. serverUrl을 제공하는 대신 커넥터의 connectorId와 authorization 토큰을 전달하세요. 그러면 Responses API가 인증을 처리하고 커넥터의 도구를 호스티드 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에 있습니다.

2. Streamable HTTP MCP 서버

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

import { Agent, run, MCPServerStreamableHttp } from '@openai/agents';

async function main() {
  const mcpServer = new MCPServerStreamableHttp({
    url: 'https://gitmcp.io/openai/codex',
    name: 'GitMCP Documentation Server',
  });
  const agent = new Agent({
    name: 'GitMCP Assistant',
    instructions: 'Use the tools to respond to user requests.',
    mcpServers: [mcpServer],
  });

  try {
    await mcpServer.connect();
    const result = await run(agent, 'Which language is this repo written in?');
    console.log(result.finalOutput);
  } finally {
    await mcpServer.close();
  }
}

main().catch(console.error);

생성자 옵션:

옵션	타입	비고
`url`	`string`	Streamable HTTP 서버 URL
`name`	`string`	서버에 대한 선택적 라벨
`cacheToolsList`	`boolean`	지연 시간을 줄이기 위한 도구 목록 캐시
`clientSessionTimeoutSeconds`	`number`	MCP 클라이언트 세션 타임아웃
`toolFilter`	`MCPToolFilterCallable \| MCPToolFilterStatic`	사용 가능한 도구 필터링
`toolMetaResolver`	`MCPToolMetaResolver`	호출별 MCP `_meta` 요청 필드 주입
`errorFunction`	`MCPToolErrorFunction \| null`	MCP 호출 실패를 모델이 볼 수 있는 텍스트로 매핑
`timeout`	`number`	요청당 타임아웃(밀리초)
`logger`	`Logger`	사용자 정의 로거
`authProvider`	`OAuthClientProvider`	MCP TypeScript SDK의 OAuth 공급자
`requestInit`	`RequestInit`	요청을 위한 fetch init 옵션
`fetch`	`FetchLike`	사용자 정의 fetch 구현
`reconnectionOptions`	`StreamableHTTPReconnectionOptions`	재연결 튜닝 옵션
`sessionId`	`string`	MCP 연결을 위한 명시적 세션 ID

생성자는 또한 authProvider, requestInit, fetch, reconnectionOptions, sessionId 등 MCP TypeScript‑SDK 옵션을 추가로 받을 수 있습니다. 자세한 내용은 MCP TypeScript SDK 저장소 및 문서를 참고하세요.

3. Stdio MCP 서버

표준 I/O만 노출하는 서버의 경우 fullCommand로 MCPServerStdio를 인스턴스화하세요:

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 npx',
    fullCommand: `npx -y @modelcontextprotocol/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` / `args`	`string` / `string[]`	stdio 서버를 위한 명령어와 인자
`fullCommand`	`string`	`command` + `args`의 대안인 전체 명령 문자열
`env`	`Record<string, string>`	서버 프로세스용 환경 변수
`cwd`	`string`	서버 프로세스의 작업 디렉터리
`cacheToolsList`	`boolean`	지연 시간을 줄이기 위한 도구 목록 캐시
`clientSessionTimeoutSeconds`	`number`	MCP 클라이언트 세션 타임아웃
`name`	`string`	서버에 대한 선택적 라벨
`encoding`	`string`	stdio 스트림의 인코딩
`encodingErrorHandler`	`'strict' \| 'ignore' \| 'replace'`	인코딩 오류 처리 전략
`toolFilter`	`MCPToolFilterCallable \| MCPToolFilterStatic`	사용 가능한 도구 필터링
`toolMetaResolver`	`MCPToolMetaResolver`	호출별 MCP `_meta` 요청 필드 주입
`errorFunction`	`MCPToolErrorFunction \| null`	MCP 호출 실패를 모델이 볼 수 있는 텍스트로 매핑
`timeout`	`number`	요청당 타임아웃(밀리초)
`logger`	`Logger`	사용자 정의 로거

MCP 서버 수명 주기 관리

여러 MCP 서버로 작업할 때 connectMcpServers를 사용해 함께 연결하고, 실패를 추적하며, 한 곳에서 닫을 수 있습니다. 이 도우미는 active, failed, errors 컬렉션을 가진 MCPServers 인스턴스를 반환하므로 에이전트에 정상 서버만 전달할 수 있습니다.

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() 호출(기본값은 실패 서버만 재시도)

엄격한 “전부 또는 무(all or nothing)” 연결이나 다른 타임아웃이 필요하면 connectMcpServers(servers, options)를 사용해 환경에 맞게 옵션을 조정하세요.

connectMcpServers 옵션:

옵션	타입	기본값	비고
`connectTimeoutMs`	`number \| null`	`10000`	각 서버 `connect()`의 타임아웃. 비활성화하려면 `null` 사용
`closeTimeoutMs`	`number \| null`	`10000`	각 서버 `close()`의 타임아웃. 비활성화하려면 `null` 사용
`dropFailed`	`boolean`	`true`	실패한 서버를 `active`에서 제외
`strict`	`boolean`	`false`	어떤 서버라도 연결에 실패하면 예외 발생
`suppressAbortError`	`boolean`	`true`	실패 서버는 추적하되 abort 유사 오류는 무시
`connectInParallel`	`boolean`	`false`	순차 대신 모든 서버를 동시에 연결

mcpServers.reconnect(options)에서 지원:

옵션	타입	기본값	비고
`failedOnly`	`boolean`	`true`	실패 서버만 재시도(`true`) 또는 모든 서버 재연결(`false`)

비동기 폐기(선택)

런타임이 Symbol.asyncDispose를 지원하는 경우, MCPServers는 await using 패턴도 지원합니다. TypeScript에서는 tsconfig.json에서 esnext.disposable을 활성화하세요:

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

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

await using mcpServers = await connectMcpServers(servers);

알아두면 좋은 사항

Streamable HTTP 및 Stdio 서버의 경우, Agent가 실행될 때마다 사용 가능한 도구를 확인하기 위해 list_tools()를 호출할 수 있습니다. 이 라운드트립은 특히 원격 서버에서 지연을 추가할 수 있으므로, MCPServerStdio 또는 MCPServerStreamableHttp에 cacheToolsList: true를 전달해 결과를 메모리에 캐시할 수 있습니다.

도구 목록이 변경되지 않는다고 확신할 때만 활성화하세요. 나중에 캐시를 무효화하려면 서버 인스턴스에서 invalidateToolsCache()를 호출하세요.

도구 필터링

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',
});

추가 자료

Model Context Protocol – 공식 명세
examples/mcp – 위에서 참조한 실행 가능한 데모