OpenAI Agents SDK로 MCP 서버 구축하는 방법

OpenAI Agents SDK는 이제 MCP(모델 컨텍스트 프로토콜)를 지원합니다. 이는 AI 상호 운용성에 혁신을 가져오는 기술입니다. 이를 통해 개발자는 AI 모델을 외부 도구 및 데이터 소스와 효율적으로 연결할 수 있습니다. 이 기술 가이드에서는 OpenAI Agents SDK를 사용하여 MCP 서버를 구축하는 방법을 안내하여 AI 응용 프로그램을 향상시키는 방법을 설명합니다.

💡

API 개발을 간소화하고 싶으신가요? Apidog를 사용해 보세요. 이는 API를 설계, 테스트 및 관리할 수 있는 강력한 도구로, API 개발 주기를 더 빠르게 만들어줍니다.

버튼

MCP 서버란 무엇이며 OpenAI Agents SDK와 함께 사용하는 이유는 무엇인가요?

MCP(모델 컨텍스트 프로토콜)는 애플리케이션이 대형 언어 모델(LLM)에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP를 AI 애플리케이션을 위한 USB-C 포트에 비유할 수 있습니다. 이는 AI 모델이 다양한 데이터 소스 및 도구와 원활하게 인터페이스할 수 있도록 해주는 범용 커넥터 역할을 합니다.

OpenAI Agents SDK는 MCP 서버를 통합하여 에이전트가 외부 도구 및 데이터에 접근할 수 있게 합니다. MCP 서버를 사용하면 AI 에이전트와 원격 및 로컬 리소스 간의 상호작용이 원활해집니다. 이 통합은 도구 호출의 복잡성을 줄이고 에이전트의 기능을 향상시킵니다.

OpenAI와 MCP 서버 조합으로 구축할 수 있는 몇 가지 예제는 다음과 같습니다:

🕵️‍♂️ gitingest를 사용하여 @OpenAIDevs 에이전트 SDK의 모든 문서를 다운로드했습니다.

OpenAI Agents SDK로 구축할 경우 AI 코딩 에이전트에 제공하면 매우 유용합니다.

아래 GitHub 링크에서 다운로드하세요 ⬇️ pic.twitter.com/0szZ43wMTv
— Dan Mac (@daniel_mac8) 2025년 3월 23일

OpenAI MCP 통합을 사용하는 단계

OpenAI Agents SDK로 MCP 서버를 구축하기 위한 전제 조건

시작하기 전에 다음 항목들이 준비되어 있는지 확인하세요:

시스템에 Python 3.8 이상이 설치되어 있어야 합니다.
pip를 통해 OpenAI Agents SDK를 설치해야 합니다: pip install openai-agents
일부 예제를 위해 MCP 서버 명령을 실행하기 위한 Node.js가 설정되어 있어야 합니다: npx
종속성 관리를 위한 가상 환경이 초기화된 프로젝트 디렉토리
SDK가 async/await를 사용하므로 Python의 비동기 프로그래밍에 대한 기본 이해가 필요합니다.

1단계: MCP 서버를 위한 개발 환경 설정

# 프로젝트를 위한 새 디렉토리 생성
mkdir mcp-agent-project && cd mcp-agent-project

# Python 가상 환경 초기화
python -m venv venv && source venv/bin/activate

# 필요한 종속성 설치
pip install openai-agents pyyaml

MCP 서버를 정의하기 위해 mcp_agent.config.yaml라는 구성 파일을 설정합니다. 이 구성은 로컬 파일에 접근하기 위해 파일 시스템 MCP 서버를 가리킵니다.

2단계: OpenAI Agents SDK의 MCP 서버 유형 이해하기

MCP 서버는 MCP 사양에 정의된 두 가지 유형이 있습니다:

stdio 서버: 애플리케이션의 하위 프로세스로 로컬에서 실행됩니다.
HTTP over SSE 서버: 원격으로 작동하며 URL을 통해 연결됩니다.

OpenAI Agents SDK는 이러한 서버를 처리하기 위해 두 가지 클래스를 제공합니다:

MCPServerStdio: 로컬 하위 프로세스 기반 서버용
MCPServerSse: 원격 HTTP over SSE 서버용

서버 유형은 애플리케이션의 아키텍처와 지연 요구 사항에 따라 선택합니다. Stdio 서버는 로컬 개발에 이상적이며, SSE 서버는 분산 시스템에 더 적합합니다.

3단계: MCP 서버를 OpenAI 에이전트에 연결하기

OpenAI Agents SDK에서 필요한 클래스를 가져오고 MCP 서버를 정의합니다:

from openai_agents import Agent, MCPServerStdio

# 샘플 파일의 경로 정의
samples_dir = "/path/to/your/files"

# 비동기 컨텍스트 관리자를 사용하여 서버 초기화
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    }
) as server:
    # MCP 서버에서 제공하는 도구 목록 가져오기
    tools = await server.list_tools()

    # MCP 서버를 사용하는 에이전트 생성
    agent = Agent(
        name="Assistant",
        instructions="파일 시스템 도구를 사용하여 사용자의 작업을 도와주세요.",
        mcp_servers=[server]
    )

    # 에이전트 실행
    result = await agent.run("디렉토리의 파일 목록을 나열하세요.")

이 설정을 통해 에이전트는 실행 중에 파일 시스템 도구를 동적으로 사용할 수 있습니다.

4단계: 도구 캐싱으로 성능 최적화

MCP 서버는 에이전트가 실행될 때마다 list_tools()를 호출하므로 지연을 발생시킬 수 있습니다. 특히 원격 서버에서는 더욱 그렇습니다. 이러한 오버헤드를 줄이기 위해 도구 캐싱을 활성화할 수 있습니다:

# 서버 초기화 시 캐싱 활성화
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    },
    cache_tools_list=True  # 캐싱 활성화
) as server:
    # 첫 번째 호출 후 도구 목록이 캐시됩니다.
    tools = await server.list_tools()

캐싱에 대한 중요한 고려 사항:

런타임 중 도구 목록이 변경되지 않을 것이라고 확신하는 경우에만 캐싱을 사용하세요.
도구를 업데이트해야 하는 경우 캐시를 무효화하세요: await server.invalidate_tools_cache()
캐싱은 stdio 및 SSE 서버 모두에서 작동하며, 원격 서버에서 더 큰 성능 이점을 제공합니다.

5단계: 에이전트의 워크플로우에 MCP 서버 통합 구현

MCP 서버를 에이전트와 완전히 통합하려면:

from openai_agents import Agent, MCPServerStdio, MCPServerSse

async def run_agent_with_mcp_servers():
    # 로컬 stdio MCP 서버 초기화
    local_server = MCPServerStdio(
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "./local_files"],
        },
        cache_tools_list=True
    )

    # 원격 SSE MCP 서버 초기화 (필요한 경우)
    remote_server = MCPServerSse(
        url="<https://your-remote-mcp-server.com/stream>",
        cache_tools_list=True
    )

    async with local_server, remote_server:
        # 두 서버로 에이전트 생성
        agent = Agent(
            name="MultiToolAgent",
            instructions="사용 가능한 도구를 사용하여 작업을 수행하세요.",
            mcp_servers=[local_server, remote_server]
        )

        # 에이전트 실행
        result = await agent.run("적절한 도구를 사용하여 요청된 작업을 완료하세요.")
        return result

이 접근 방식은 에이전트가 표준화된 MCP 인터페이스를 통해 로컬 및 원격 도구에 접근할 수 있게 합니다.

6단계: MCP 서버 디버깅 및 모니터링

효과적인 디버깅 및 모니터링 전략은 다음을 포함합니다:

도구 실행 중 오류에 대한 MCP 서버 로그 확인
OpenAI Agents SDK의 추적 대시보드를 사용하여 도구 호출 모니터링
잘못된 도구 이름 또는 서버 다운타임과 같은 엣지 케이스 테스트하여 안정성 확보
원격 SSE 서버를 사용할 때 지연 모니터링하고 필요한 경우 캐싱으로 최적화
자동으로 capture되는 SDK의 내장 추적 기능 활용:

도구 목록을 나열하기 위해 MCP 서버에 대한 호출
함수 호출에 대한 MCP 관련 정보

또한, API 개발 주기를 더 간소화하려면 올인원 API 테스트 도구를 사용하는 것도 고려해야 합니다.

Apidog는 API 개발을 단순화하는 강력한 도구로, OpenAI Agents SDK로 MCP 서버를 구축할 때 훌륭한 동반자가 됩니다. MCP 서버는 종종 원격 HTTP over SSE 서버든 도구 호출 테스트에서든 API와 상호작용하므로 Apidog는 워크플로를 향상시킬 수 있습니다.

버튼

결론

OpenAI Agents SDK로 MCP 서버를 구축하면 외부 도구 및 데이터 소스와 함께 AI 에이전트를 향상시킬 수 있는 새로운 가능성이 열립니다. 표준화된 MCP 인터페이스는 다양한 환경에서 통합을 더 간단하고 신뢰할 수 있게 만듭니다.

이 가이드를 따르면 모델 컨텍스트 프로토콜을 통해 로컬 및 원격 리소스를 활용하는 강력한 에이전트를 생성할 수 있습니다. MCP 생태계가 계속 성장함에 따라 에이전트는 점점 더 확장되는 도구 및 기능 세트에 접근할 수 있게 됩니다.

자세한 문서 및 추가 예제를 보려면 OpenAI Agents SDK MCP 공식 문서를 방문하세요. MCP에 대한 SDK의 지원은 AI 에이전트를 더 능력 있고 디지털 세계와 연결되도록 만드는 중요한 진전을 나타냅니다.

버튼