Skip to main content

OpenAI 에이전트로 시작하는 MCP 가이드

Weave를 통해 도구, 파일, 추적 데이터를 접근하기 위해 Model Context Protocol(MCP)을 사용하는 OpenAI 에이전트를 구축하는 실전 가이드. 이 글은 AI 번역본입니다. 오역이 의심되는 부분은 댓글로 알려주세요.
Created on September 12|Last edited on September 12
파일 시스템이나 분석 플랫폼 같은 외부 도구에 연결해 OpenAI 에이전트를 더 똑똑하게 만들고 싶으신가요?
이 가이드는 Model Context Protocol(MCP)을 사용해 에이전트를 구조화된 도구에 연결하는 방법을 설명합니다. 파일부터 시작해 강력한 Weights & Biases 통합까지 단계적으로 다룹니다.
💡
OpenAI의 Agents SDK 은 도구를 사용하고 컨텍스트에 접근하며 실제 데이터에 대해 추론할 수 있는 AI 어시스턴트를 구축하기 위한 강력한 프레임워크를 제공합니다. 하지만 에이전트가 유용한 일을 하려면 API, 파일, 서비스, 기타 도구 같은 외부 시스템에 구조적으로 접근할 수 있어야 합니다. 바로 그 지점에서 Model Context Protocol (MCP) 등장합니다.
MCP 은 다음을 정의하는 오픈 표준입니다. LLM 기반 애플리케이션 처럼 에이전트 외부 리소스에 연결할 수 있습니다. 이를 통해 에이전트는 각 사용 사례마다 맞춤형 통합에 의존하지 않고도 도구, 문서, 사전에 정의된 프롬프트와 상호작용하기 위한 깔끔하고 일관된 인터페이스를 사용할 수 있습니다.
이 가이드에서는 MCP를 활용하는 방법을 단계별로 살펴보겠습니다. OpenAI 에이전트간단한 예시부터 시작하겠습니다. 공식 filesystem 서버를 사용해 에이전트가 파일 폴더를 탐색하고 그 내용을 기반으로 추론하도록 해 보겠습니다. 이를 통해 에이전트가 MCP를 사용해 동적으로 확장 가능한 방식으로 외부 세계와 상호작용하는 방법을 보여 드립니다.


목차



Model Context Protocol(MCP)이란 무엇인가요?

Model Context Protocol(MCP)은 LLM 애플리케이션이 외부 도구, 데이터, 프롬프트 템플릿에 접근할 수 있도록 통합되고 안전한 인터페이스를 제공하는 개방형 표준입니다. 리소스 접근을 표준화하여 통합 과정을 간소화하고, 다양한 AI 플랫폼 전반에서 일관된 배포를 가능하게 합니다.
LLM 예를 들어 다음과 같은 애플리케이션 챗봇 정확하고 동적인 응답을 제공하기 위해 외부 리소스에 의존합니다. 이러한 리소스는 다음 세 가지 핵심 범주로 나뉩니다:
  • 도구 모델이 데이터베이스 조회나 이메일 보내기와 같은 작업을 실행할 수 있도록 합니다.
  • 리소스: 모델이 참고할 수 있도록 문서, 로그, API 응답과 같은 구조화된 데이터를 제공합니다.
  • 프롬프트: 상호작용을 안내하여 일관성과 효율성을 보장하는 사전 정의된 템플릿입니다.
표준화된 프레임워크가 없으면, LLM 기반 애플리케이션마다 이러한 리소스에 연결하는 자체 방식을 만들어야 하므로 불필요한 복잡성과 중복 개발이 발생합니다. MCP는 공통 프로토콜을 제공하여 이 문제를 해결하며, 개발자가 한 번만 구현해도 여러 AI 플랫폼에 손쉽게 배포할 수 있게 합니다.

OpenAI는 MCP를 지원하나요?

네, OpenAI의 Agents SDK는 MCP를 기본으로 지원합니다. 이 내장 기능을 통해 SDK로 만든 에이전트는 하나 이상의 MCP 서버에 연결하여 별도의 커스텀 통합 없이 외부 도구, 데이터, 프롬프트 템플릿에 원활하게 접근할 수 있습니다. 효율성을 염두에 두고 설계되었습니다.
에이전트를 구성할 때 다음을 사용하여 MCP 서버를 등록할 수 있습니다 mcp_servers 인자입니다. SDK는 검색, 도구 실행, 응답 라우팅을 자동으로 관리합니다. 로컬(MCPServerStdio)과 원격(MCPServerSse) 서버를 모두 지원하여 로컬 스크립트부터 클라우드 API까지 손쉽게 통합할 수 있습니다.
이 통합을 통해 파일 브라우저, SQL 인터페이스, 웹 도구와 같은 MCP 호환 서버 생태계가 열리며, 별도의 커스텀 코드 없이도 여러 에이전트에서 재사용할 수 있습니다. 더 나아가, 한 에이전트를 위해 만든 도구는 MCP 규격을 따르는 어떤 환경에서도 작동합니다.

튜토리얼: MCP와 Weights & Biases를 활용한 지능형 파일 탐색 에이전트 만들기

이제 MCP가 무엇이며 OpenAI Agents SDK와 어떻게 맞물리는지 살펴봤으니, 간단한 예제를 통해 직접 확인해 보겠습니다.
이 튜토리얼에서는 MCP를 사용해 파일 폴더를 탐색할 수 있는 에이전트를 만들어 보겠습니다. 에이전트는 공식 server-filesystem MCP 서버를 활용해 텍스트 파일의 목록을 조회하고, 내용을 읽고, 그 내용을 바탕으로 추론까지 수행합니다. 별도의 커스텀 통합은 필요하지 않습니다.
먼저 몇 가지 패키지를 설치하고 예제 파일을 클론한 뒤, MCP를 통해 에이전트를 filesystem 서버에 연결하는 스크립트를 실행하겠습니다. 이렇게 하면 에이전트가 사용 가능한 도구를 동적으로 발견하고 실제 데이터에 기반해 질문에 답하는, 처음부터 끝까지 동작하는 환경이 갖춰집니다.
python -m venv env
source env/bin/activate
pip install openai-agents weave
curl -Ls https://astral.sh/uv/install.sh | sh
다음으로, 아래 명령으로 예제 파일을 클론하세요:
git clone --depth=1 https://github.com/openai/openai-agents-python.git temp_agents && cp -R temp_agents/examples/mcp/filesystem_example/sample_files ./ && cp temp_agents/examples/mcp/filesystem_example/main.py ./ && rm -rf temp_agents
이제 다음이 준비되어 있어야 합니다:
sample_files/
main.py
원하신다면 추가로 Weave OpenAI 에이전트에 로깅을 추가하려면, 아래 코드를 사용해 main.py를 교체하세요. 이 파일은 npx를 통해 MCP 서버를 실행하여 에이전트가 파일에 접근하고, MCP 도구 호출로 파일 목록 조회, 읽기, 분석을 수행할 수 있도록 합니다.
다음 명령으로 에이전트를 실행하세요:
import asyncio
import os
import shutil

from agents import Agent, Runner, set_trace_processors
from agents.mcp import MCPServer, MCPServerStdio
from weave.integrations.openai_agents.openai_agents import WeaveTracingProcessor
import weave

# Initialize Weave project
weave.init("mcp_stuff")
set_trace_processors([WeaveTracingProcessor()]) # Enable Weave tracing

async def run(mcp_server: MCPServer):
agent = Agent(
name="Assistant",
instructions="Use the tools to read the filesystem and answer questions based on those files.",
mcp_servers=[mcp_server],
)

message = "Read the files and list them."
print(f"Running: {message}")
result = await Runner.run(starting_agent=agent, input=message)
print(result.final_output)

message = "What is my #1 favorite book?"
print(f"\n\nRunning: {message}")
result = await Runner.run(starting_agent=agent, input=message)
print(result.final_output)

message = "Look at my favorite songs. Suggest one new song that I might like."
print(f"\n\nRunning: {message}")
result = await Runner.run(starting_agent=agent, input=message)
print(result.final_output)

async def main():
current_dir = os.path.dirname(os.path.abspath(__file__))
samples_dir = os.path.join(current_dir, "sample_files")

async with MCPServerStdio(
name="Filesystem Server, via npx",
params={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
},
) as server:
await run(server)

if __name__ == "__main__":
if not shutil.which("npx"):
raise RuntimeError("npx is not installed. Please install it with `npm install -g npx`.")
asyncio.run(main())
main.py 파일은 서브프로세스로 MCP 서버를 실행합니다 npx @modelcontextprotocol/server-filesystem, 에이전트가 다음에 접근할 수 있도록 sample_files 디렉터리입니다. 에이전트는 MCP 도구 호출을 사용해 파일을 나열하고, 읽고, 분석합니다.
다음 명령으로 실행할 수 있습니다:
uv run python main.py
스크립트를 실행한 뒤에는 에이전트가 다음 위치의 파일을 탐색합니다 sample_files 디렉터리를 탐색하고 우리가 던진 질의인 “내가 가장 좋아하는 책은 무엇인가요?”에 답합니다.


OpenAI 에이전트와 W&B MCP 서버 통합

이제 간단한 예제를 마쳤으니, W&B Weave MCP 서버를 사용하는 좀 더 발전된 사용 사례로 넘어가겠습니다. Weave는 상세한 트레이스 데이터를 기록해 LLM 에이전트의 동작을 점검하고 분석하는 플랫폼입니다. 이 예제에서는 OpenAI Agents로 구동되는 챗봇을 만들고, MCP를 사용해 Weave 서버에 연결하여 트레이스 데이터를 조회하고 시각화하는 방법을 보여줍니다.
먼저 W&B Weave를 클론하세요 MCP 서버 코드:
git clone https://github.com/wandb/mcp-server.git
저장소에서 서버 스크립트의 경로를 확인하세요. 그런 다음 Weave에 연결된 챗봇으로 동작하는 새 스크립트를 만듭니다. 이 스크립트는 stdio를 통해 MCP 프로토콜을 사용하는 OpenAI Agents를 활용하고, Weave의 트레이싱 기능을 이용해 에이전트 상호작용을 기록하고 조회합니다. 이 구성으로 “byyoung3/qat 프로젝트에서 최근 LLM 활동에 대한 보고서를 생성해줘” 같은 질의를 수행하고, 상세한 출력 결과를 확인할 수 있습니다.
import asyncio
import os
import shutil

from agents import Agent, Runner, set_trace_processors
from agents.mcp import MCPServerStdio
from weave.integrations.openai_agents.openai_agents import WeaveTracingProcessor
import weave

weave.init("oai_agent")
set_trace_processors([WeaveTracingProcessor()]) # Enables automatic Weave tracing

SERVER_DIR = "/Users/brettyoung/Desktop/dev_24/tutorials/oai_mcp/mcp-server/src/mcp_server" # put your full path to the weave server here
UV_PATH = shutil.which("uv")

async def setup_agent():
mcp_server = MCPServerStdio(
name="Weave MCP Server (via uv)",
params={
"command": UV_PATH,
"args": ["--directory", SERVER_DIR, "run", "server.py"],
},
)
await mcp_server.__aenter__()
agent = Agent(
name="Assistant",
instructions="Use the tools to query Weave or analyze traces to answer questions.",
mcp_servers=[mcp_server],
)
return agent, mcp_server

# @weave.op
async def chat_loop(agent):
print("\nChat with the Weave Agent (type 'exit' to quit):\n")
while True:
msg = input("You: ").strip()
if msg.lower() in ["exit", "quit"]:
break
result = await Runner.run(starting_agent=agent, input=msg)
print(f"Assistant: {result.final_output}\n")

async def main():
if not UV_PATH:
raise RuntimeError("uv not found in PATH")
agent, mcp_server = await setup_agent()
try:
await chat_loop(agent)
finally:
await mcp_server.__aexit__(None, None, None)

if __name__ == "__main__":
asyncio.run(main())

스크립트는 다음과 같은 작업을 수행합니다:
  1. 에이전트 상호작용을 추적하기 위해 Weave를 초기화합니다.
  2. uv로 Weave MCP 서버를 실행하고 stdio로 연결합니다.
  3. 프로젝트, 트레이스, 메트릭을 조회하기 위한 Weave의 도구에 접근할 수 있는 에이전트를 생성합니다.
  4. 메시지 히스토리를 유지해 문맥을 보존하는 REPL 스타일의 채팅 루프를 실행하여, 에이전트와 자연스럽게 상호작용할 수 있게 합니다.
이제 스크립트를 실행하고 다음과 같은 질문을 시작할 수 있습니다:
generate a report of recent LLM activity in the byyoung3/qat project

쿼리를 입력하면 에이전트가 Weave MCP 서버에 질의를 시작하고, Weave 내부에 있는 “qat” 프로젝트의 최근 트레이스에 대한 보고서를 생성합니다.


결론

이 가이드는 OpenAI Agents, MCP 프로토콜, 그리고 W&B Weave가 로컬 및 원격 기능을 바탕으로 지능형 도구를 함께 구축하는 방법을 빠르게 익히기 위한 간단한 안내입니다.
로컬에서 Weave MCP 서버를 사용하고 에이전트에 stdio를 통해 접근 권한을 부여함으로써, 에이전트 동작에 대한 심층적인 내관이 가능해졌으며, 과거 실행 이력까지 조회할 수 있게 되었습니다. 보고서를 생성하다그리고 여러 프로젝트에 걸친 사용 패턴을 분석할 수 있습니다. MCP는 에이전트와 외부 세계를 연결하는 접착제 역할을 하여, 어떤 도구나 데이터베이스, 서비스를 에이전트가 이해하고 활용할 수 있는 대상으로 바꿔 줍니다. 또한 Weave는 관측 계층으로서, 에이전트의 사고 과정을 단계별로 점검하고 디버깅하며 모니터링할 수 있게 해 줍니다.
이 스택을 함께 사용하면 파일 탐색, 인프라 관리, 프로덕션 텔레메트리 질의 등 어떤 작업이든 강력하고 내관 가능한 에이전트를 구축할 수 있는 기반을 갖추게 됩니다.
당신은 할 수 있습니다 여기로 이동하세요 OpenAI에서 제공하는 몇 가지 추가 예시는 다음을 참고하세요.

이 글은 AI로 번역되었습니다. 오역이 의심되는 부분은 댓글로 알려주세요. 원문은 아래 링크에서 확인하실 수 있습니다: 원문 보고서 보기