MCP Agent 완벽 가이드: OpenAI SDK로 AI 에이전트 만들기
최근 들어 AI 에이전트의 활용 범위가 빠르게 확장되고 있습니다. 특히, 다양한 앱과 실제로 상호작용하며 업무를 자동화할 수 있는 MCP (Model Context Protocol) 기반 에이전트는 주목할 만한 기술입니다.
MCP는 단순한 챗봇이나 스크립트를 넘어서, 실제 앱에 연결되어 데이터를 주고받고 실행까지 할 수 있도록 만들어줍니다. 예를 들어, GitHub에 이슈를 생성하거나 Gmail로 이메일을 보내는 등 복잡한 작업도 가능하죠.
하지만 MCP 에이전트를 직접 개발하려면 많은 컴포넌트와 개념을 이해해야 하고, 프레임워크도 다양하기 때문에 처음 접하는 사람에겐 다소 어렵게 느껴질 수 있습니다.
이번 글에서는 MCP의 개념부터 구조, 대표적인 SDK, 실습 예제까지 전부 다룰 것입니다. 특히, OpenAI의 공식 SDK를 이용해 처음부터 끝까지 에이전트를 만드는 과정을 상세히 소개하고, 다른 프레임워크를 이용한 예제도 함께 제시할 예정입니다.
이 글은 단순한 개념 설명을 넘어서, 실습 중심으로 실제 작동하는 MCP 에이전트를 만들 수 있도록 구성했습니다. 개발자라면 실무에서 활용 가능한 예제와 함께, 커스터마이징 가능한 기반 코드를 제공받을 수 있으며, MCP의 작동 원리를 체계적으로 익힐 수 있습니다. SEO 최적화를 고려해 구성했기 때문에, 필요한 정보를 쉽게 찾고 이해하실 수 있습니다.
- Github 기반 최고의 오픈소스 개발 도구 Best10
- MCP(Modular Control Protocol) 개념과 통합 사례 10가지
- AI 에이전트 구축 실전 가이드: 개념부터 배포까지
아래에서는 MCP의 핵심 구조와 함께, MCP Agent 개발을 위한 프레임워크 및 실습 예제를 순서대로 소개합니다.
MCP란?
Model Context Protocol(MCP)은 애플리케이션이 대규모 언어 모델(LLM)에게 컨텍스트와 도구를 제공하는 방식을 표준화한 새로운 오픈 프로토콜입니다. 쉽게 말해, AI를 위한 범용 커넥터 역할을 하며, Cursor, Claude, Windsurf 같은 MCP 클라이언트가 다양한 데이터 소스와 도구에 연결할 수 있게 해주는 플러그인 시스템입니다.
예를 들어, Obsidian용 MCP 서버는 AI 어시스턴트가 사용자의 Obsidian 볼트에서 노트를 검색하고 읽을 수 있도록 도와줍니다. 이처럼 MCP는 LLM 위에 에이전트와 복잡한 워크플로우를 구축할 수 있게 해주는 핵심 기술입니다.
MCP의 핵심 구성 요소
MCP는 클라이언트-서버 아키텍처를 따르며, 다음과 같은 주요 구성 요소로 이루어져 있습니다.
- MCP 호스트: Claude Desktop, Cursor, Windsurf 등 MCP를 통해 데이터에 접근하려는 AI 도구들
- MCP 클라이언트: MCP 서버와 1:1 연결을 유지하며 통신 브리지 역할을 하는 프로토콜 클라이언트
- MCP 서버: 파일 읽기, 데이터베이스 쿼리 등 특정 기능을 표준화된 프로토콜을 통해 노출하는 경량 프로그램
- 로컬 데이터 소스: MCP 서버가 안전하게 접근할 수 있는 컴퓨터의 파일, 데이터베이스, 서비스
- 원격 서비스: MCP 서버가 연결할 수 있는 외부 API와 클라우드 기반 시스템
MCP 에이전트의 아키텍처
MCP 에이전트는 MCP 프로토콜을 통해 추론하고, 도구에 접근하며, 메모리를 사용하고, 행동을 취하도록 설계되었습니다. 에이전트의 아키텍처는 세 개의 주요 레이어로 구성됩니다.
- 모델 컨텍스트 레이어 – 두뇌
언어 모델(LLM)이 에이전트의 두뇌 역할을 합니다. GPT-4나 Claude 같은 LLM이 자연어 요청을 처리하며, 사용 가능한 도구/리소스와 행동 지침 프롬프트에 의해 안내됩니다. - 프로토콜 레이어 – 신경계
에이전트가 외부 세계를 감지하고 소통하는 방법입니다. 여기에는 통신 브리지 역할을 하는 MCP 클라이언트(Cursor, Claude Desktop)와 특정 도구(Gmail, Notion, 파일시스템)에 대한 커넥터 역할을 하는 MCP 서버가 포함됩니다. - 런타임 레이어 – 근육
실제로 행동을 수행하는 부분입니다. 도구/API를 위한 실행 환경이며, 초안 메시지나 중간 단계 같은 단기 상태를 유지합니다.
MCP 에이전트 구축을 위한 프레임워크
MCP 에이전트를 구축하기 위한 다양한 프레임워크와 SDK가 있습니다. 선택 기준은 사용하는 언어나 기술 스택, 관리형 설정 vs 자체 호스팅 환경, 연결하려는 앱의 기본 지원 여부입니다.
주요 프레임워크 목록
OpenAI Agents SDK: OpenAI 플랫폼을 사용한 어시스턴트 구축을 위한 퍼스트파티 지원
bashpip install openai-agents
Composio With OpenAI: Composio 관리형 MCP 서버와 OpenAI 에이전트를 통합하는 경량 SDK
pip install composio-openai
openai
mcp-agent by LastMile AI: MCP와 간단한 워크플로우 패턴을 사용해 에이전트를 구축하는 간단하고 조합 가능한 프레임워크
pip install mcp-agent
MCP Python SDK: 전체 MCP 사양을 구현하는 공식 Python SDK
pip install “mcp[cli]”
MCP TypeScript SDK: 전체 MCP 사양을 구현하는 공식 TypeScript/Node SDK
npm install @modelcontextprotocol/sdk
OpenAI SDK로 MCP Agent 만들기
이제 실제로 MCP Agent를 개발하는 과정을 살펴보겠습니다.
1단계: 개발 환경 준비와 프로젝트 초기 설정
Python 설치 및 버전 확인
우선 Python 3.8 이상의 환경이 필요합니다. 터미널에서 다음 명령어로 설치 여부 및 버전을 확인합니다:
python --version
가상환경(Virtual Environment) 생성
가상환경을 사용하면 프로젝트별로 독립된 패키지 관리를 할 수 있어 충돌을 방지할 수 있습니다.
# macOS/Linux
python3 -m venv env
source env/bin/activate
# Windows
python -m venv env
.\\env\\Scripts\\activate
터미널 프롬프트에 (env)가 표시되면 가상환경이 정상적으로 활성화된 것입니다.
2단계: 필요한 패키지 설치 및 환경 변수 구성
필요한 패키지 설치
pip install openai-agents python-dotenv
openai-agents: OpenAI 공식 SDK로, MCP 서버 연동 및 툴 사용 가능
python-dotenv: .env 파일의 환경변수를 Python 코드에서 사용할 수 있게 해줌
requirements.txt 생성
pip freeze > requirements.txt
이렇게 하면 현재 가상환경에서 설치된 모든 패키지를 requirements.txt로 저장할 수 있습니다.
.env 파일 작성
루트 디렉토리에 .env 파일을 생성한 후 다음 내용을 입력합니다:
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
MCP_TOOL_URL=https://mcp.composio.dev/github/sse?customerId=your_customer_id
⚠️ API 키는 OpenAI 계정에서 발급받아야 하며, Composio의 GitHub MCP 서버 주소도 미리 받아야 합니다.
3단계: 에이전트 코드 작성
프로젝트 구조 구성
다음과 같은 프로젝트 디렉토리 구조를 따릅니다.
mcp-openai-agent/
├── agent.py # 에이전트 정의
├── run_agent.py # 실행 스크립트
├── requirements.txt # 패키지 목록
├── .env # 환경변수
└── README.md
agent.py: MCP Agent 정의
import os
import openai
from agents import Agent
from agents.mcp import MCPServerSse
from dotenv import load_dotenv
load_dotenv()
openai.api_key = os.getenv("OPENAI_API_KEY")
TOOL_URL = os.getenv("MCP_TOOL_URL")
def build_agent():
mcp_server = MCPServerSse({"url": TOOL_URL})
agent = Agent(
name="GitHub Agent",
instructions=(
"사용자의 GitHub 작업을 자동화합니다. "
"이슈 생성, PR 관리, 레포지토리 업데이트 등을 수행합니다."
),
mcp_servers=[mcp_server],
)
return agent, mcp_server
주요 설명
MCPServerSse: MCP 서버와 연결 (SSE 방식)Agent: 이름, 역할, MCP 서버 연결 정보를 포함한 에이전트 생성build_agent(): 에이전트와 MCP 서버 인스턴스를 반환
run_agent.py: MCP Agent 실행 스크립트
import asyncio
from agent import build_agent
from agents import Runner
TASK = (
"Anmol-Baranwal/mcp-agents 레포지토리에 이슈 생성: "
"제목은 'Feat: MCP Server Implemented', "
"본문은 'just testing stuff.'로 설정해주세요."
)
async def main():
agent, mcp_server = build_agent()
try:
await mcp_server.connect()
result = await Runner.run(agent, TASK)
print("최종 결과:\\n", result.final_output)
finally:
await mcp_server.cleanup()
if __name__ == "__main__":
asyncio.run(main())
주요 설명
Runner.run(agent, TASK): 모델에 작업을 전달하고 툴 호출 수행- MCP 서버가 연결되면 OAuth 인증 URL이 출력됩니다.
- 인증 후 재실행하면 에이전트가 GitHub 이슈 생성 작업을 수행합니다.
Composio MCP 서버 연결 방법
Composio 플랫폼은 MCP 서버를 관리형으로 제공하며, GitHub, Gmail, Notion 등 250개 이상의 툴을 바로 연결할 수 있습니다.
- https://mcp.composio.dev 접속
- 원하는 MCP 툴(GitHub)을 선택
SSE URL복사 (https://mcp.composio.dev/github/sse?customerId=xyz).env파일에 해당 URL을 입력
OAuth 인증이 필요한 경우, 터미널에 나오는 URL을 브라우저에 붙여넣고 인증 후 진행합니다.
실습 결과 확인 및 디버깅 팁
- 이슈 생성이 안 될 경우:
- GitHub 레포지토리가 비공개라면 권한 오류가 발생할 수 있음
- 인증이 완료되지 않았거나, API 키/URL 오류 가능성 있음
- 인증 확인 방법:
- OAuth 인증 URL 접속 후, “연결됨” 메시지가 출력되는지 확인
- Composio 대시보드에서 연결된 서비스 목록 확인
- 커스터마이징 팁:
- 다른 툴(Gmail, Notion 등)도 URL만 바꾸면 같은 방식으로 연결 가능
- instructions 부분에 원하는 행동 지침을 구체적으로 적어 에이전트의 행동을 조정 가능
MCP Agent 확장 예시: 이메일 보내기 에이전트
.env 파일에 Gmail MCP 서버 URL을 추가하고, 다음 코드로 실행 가능:
TOOL_URL=https://mcp.composio.dev/gmail/sse?customerId=your_id
from agents import Agent, Runner
from agents.mcp import MCPServerSse
import os
from dotenv import load_dotenv
load_dotenv()
async def main():
server = MCPServerSse({"url": os.getenv("MCP_TOOL_URL")})
await server.connect()
agent = Agent(
name="Gmail Agent",
instructions="Gmail을 통해 이메일을 보냅니다.",
mcp_servers=[server],
)
task = (
"hi@anmolbaranwal.com에게 제목 'Hello from MCP Agent'와 "
"본문 '이것은 테스트 이메일입니다'로 메일을 보내세요."
)
result = await Runner.run(agent, task)
print(result.final_output)
await server.cleanup()
MCP 에이전트의 장점과 활용 분야
MCP 에이전트는 다음과 같은 강력한 장점을 제공합니다:
통합된 워크플로우: 여러 애플리케이션과 서비스를 하나의 에이전트로 통합해 복잡한 업무를 자동화할 수 있습니다.
확장성: 새로운 MCP 서버를 추가하기만 하면 에이전트의 기능을 쉽게 확장할 수 있습니다.
보안성: 표준화된 프로토콜을 통해 안전한 데이터 접근과 권한 관리가 가능합니다.
개발 편의성: 다양한 프레임워크와 SDK를 통해 개발자가 쉽게 에이전트를 구축할 수 있습니다.
주요 활용 분야
- 업무 자동화: 이메일 관리, 일정 조율, 문서 작성 등
- 개발 워크플로우: GitHub 이슈 관리, 코드 리뷰, 배포 자동화
- 콘텐츠 관리: 블로그 포스팅, 소셜 미디어 관리, 문서 정리
- 데이터 분석: 다양한 소스에서 데이터 수집 및 분석
- 고객 서비스: 자동 응답, 티켓 관리, FAQ 처리
FAQ: MCP 에이전트 관련 자주 묻는 질문
Q1. MCP 에이전트와 일반 AI 챗봇의 차이점은 무엇인가요?
일반 AI 챗봇은 단순히 텍스트 대화만 가능하지만, MCP 에이전트는 실제 애플리케이션과 연결되어 구체적인 작업을 수행할 수 있습니다. 예를 들어, 이메일 전송, GitHub 이슈 생성, 파일 관리 등의 실제 업무를 처리할 수 있습니다.
Q2. MCP 에이전트를 구축하려면 어떤 기술적 배경이 필요한가요?
기본적인 Python 프로그래밍 지식과 API 사용 경험이 있으면 충분합니다. 복잡한 머신러닝 지식은 필요하지 않으며, 제공되는 SDK와 프레임워크를 활용하면 비교적 쉽게 구축할 수 있습니다.
Q3. MCP 에이전트의 보안은 어떻게 보장되나요?
MCP는 표준화된 프로토콜을 통해 안전한 인증과 권한 관리를 제공합니다. OAuth, API 키, JWT 등 다양한 인증 방식을 지원하며, 각 서비스별로 필요한 권한만 부여할 수 있습니다.
Q4. 어떤 애플리케이션과 연결할 수 있나요?
Gmail, Slack, Notion, GitHub, Linear 등 250개 이상의 도구와 연결할 수 있습니다. Composio 같은 관리형 서비스를 사용하면 별도의 설정 없이도 다양한 애플리케이션에 쉽게 연결할 수 있습니다.
Q5. MCP 에이전트 구축에 비용이 많이 드나요?
OpenAI API 사용료와 선택한 MCP 서버 서비스 비용만 발생합니다. 대부분의 MCP 프레임워크는 오픈소스이며, 소규모 프로젝트의 경우 월 몇 달러 수준의 비용으로도 충분히 운영할 수 있습니다.
Q6. MCP 에이전트의 성능은 어느 정도인가요?
사용하는 LLM 모델과 연결된 서비스의 응답 속도에 따라 달라집니다. 일반적으로 간단한 작업은 몇 초 내에, 복잡한 워크플로우도 1-2분 내에 완료됩니다.
Q7. 여러 개의 MCP 서버를 동시에 사용할 수 있나요?
네, 하나의 에이전트에 여러 MCP 서버를 연결할 수 있습니다. 예를 들어, Gmail과 Notion을 동시에 연결해 이메일을 읽고 내용을 노션에 정리하는 복합적인 작업도 가능합니다.
Q8. MCP 에이전트를 상용 서비스에 적용할 수 있나요?
물론입니다. 많은 기업들이 이미 MCP 에이전트를 활용해 고객 서비스, 업무 자동화, 데이터 처리 등의 상용 서비스를 제공하고 있습니다. 다만 서비스 규모에 따른 적절한 인프라 설계가 필요합니다.
맺음말
MCP 에이전트는 AI가 단순한 대화를 넘어 실제 업무를 처리할 수 있게 해주는 혁신적인 기술입니다. OpenAI SDK, Composio, mcp-agent 등 다양한 프레임워크를 통해 누구나 쉽게 MCP 에이전트를 구축할 수 있으며, 이를 통해 업무 효율성을 크게 향상시킬 수 있습니다.
MCP는 아직 진화하고 있는 기술이지만, 기본 개념은 동일하게 유지될 것입니다. 더 많은 엣지 케이스가 발견됨에 따라 미래에는 더 많은 프레임워크가 등장할 것으로 예상됩니다.
지금이야말로 MCP 에이전트를 활용해 혁신적인 AI 솔루션을 구축할 최적의 시기입니다. 실용적이고 유용한 것을 만들어 세상에 워크플로우와 컨텍스트가 만날 때 어떤 가능성이 열리는지 보여주세요.
