Show HN: 에이전트를 MCP 서버로 표현하기

이 디렉토리는 MCP 에이전트 워크플로우를 MCP 서버로 노출하는 예제를 제공합니다. 다양한 실행 환경에서 에이전트 기반 MCP 서버를 구축, 시작 및 상호 작용하는 방법을 보여줍니다.

MCP Agent Server 패턴은 에이전트 아키텍처의 중요한 진화입니다. 전통적인 MCP 클라이언트 (Claude, Cursor, VS Code 등) 는 종종 MCP 서버 도구를 소비하는 에이전트로 행동하지만, 이 예제는 패러다임을 뒤집습니다:

에이전트를 서버로: 에이전트 워크플로우를 MCP 서버로 패키징하기
에이전트 상호 운용성: 표준 프로토콜을 통해 다중 에이전트 상호 작용 가능
결합되지 않은 아키텍처: 에이전트 로직과 클라이언트 인터페이스를 분리

Screen.Recording.2025-05-01.at.12.41.21.AM.mov

에이전트 컴포지션: 에이전트가 서로 상호 작용할 수 있는 복잡한 다중 에이전트 시스템 구축
플랫폼 독립성: MCP 호환 클라이언트에서 에이전트를 사용
확장성: 전용 인프라에서, 클라이언트 환경 내에서만 실행하지 않고 에이전트 워크플로우 실행
재사용성: 한 번에 에이전트 워크플로우 생성하고 여러 클라이언트 및 환경에서 사용
캡슐화: 복잡한 에이전트 로직을 잘 정의된 자체 포함 인터페이스로 패키징

이 디렉토리는 MCP Agent Server 패턴의 두 가지 구현을 포함합니다:

asyncio 구현은 다음을 제공합니다:

• 최소한의 설정으로 메모리 내 실행
• 외부 의존성 없이 간단한 배포
• 빠른 시작 및 실행
• 개발, 테스트 및 덜 복잡한 에이전트 워크플로우에 적합

Temporal 구현은 다음을 제공합니다:

• Temporal 을 오케스트레이션 엔진으로 사용하여 워크플로우의 내구적 실행
• Temporal 신호를 통한 일시 정지/이동 기능
• 실패에서 자동 재시도 및 복구
• Temporal UI 를 통한 워크플로우 관찰 가능성
• 복잡한 에이전트 워크플로우 및 프로덕션 배포에 이상적

각 구현은 다음을 보여줍니다:

BasicAgentWorkflow: LLM 을 사용하여 입력을 처리하는 간단한 에이전트 워크플로우
ParallelWorkflow(asyncio) 또는 PauseResumeWorkflow(temporal): 병렬 실행이나 신호링 기능을 보여주는 더 복잡한 패턴

기능	설명
프로토콜 표준화
에이전트는 상호 운용성을 보장하기 위해 표준화된 MCP 프로토콜을 통해 통신
워크플로우 캡슐화
복잡한 에이전트 워크플로우는 간단한 MCP 도구로 노출됨
실행 유연성
메모리 내 (asyncio) 또는 내구적 (Temporal) 실행 선택
클라이언트 독립성
Claude, VSCode, Cursor, MCP Inspector 또는 커스텀 앱에서 연결
다중 에이전트 생태계
여러 에이전트가 상호 작용하고 협력할 수 있는 시스템 구축

각 구현 디렉토리는 자세한 지침이 포함된 자체 README 를 포함합니다. 가장 간단한 개발자 경험을 위해 장식기 기반 도구 정의 (@app.tool / @app.async_tool) 를 선호하세요:

워크플로우 클래스만 정의하는 대신, 함수에서 직접 도구를 노출할 수 있습니다:

from mcp_agent.app import MCPApp
app = MCPApp(name="my_agent_server")
@app.tool
...

• 동기 도구: 최종 결과를 반환하며 상태 폴링 필요 없음.
• 비동기 도구: 일반적인 workflows-get_status 엔드포인트를 통해 폴링을 위해 ID 를 반환합니다.

MCP Agent Server 패턴이 가능하게 하는 가장 강력한 기능 중 하나는 다중 에이전트 상호 작용입니다. 여기에는 개념적 예제가 있습니다:

┌────────────────┐ ┌────────────────┐
│ │ │ │
│ Research │ MCP │ Writing │
...

이 예제에서:

• Claude Desktop 은 두 에이전트 서버 모두를 사용할 수 있습니다.
• Writing Agent 는 Research Agent 를 도구로 사용할 수도 있습니다.
• 모든 통신은 MCP 프로토콜을 통해 이루어집니다

이 예제는 다양한 클라이언트와 MCP Agent 서버를 통합하는 방법을 보여줍니다:

Claude Desktop 을 에이전트 서버에 액세스하도록 구성하려면 ~/.claude-desktop/config.json 을 업데이트하세요:

"my-agent-server": {
"command": "/path/to/uv",
"args": [
...

MCP Inspector 를 사용하여 에이전트 서버를 탐색하고 테스트하세요:

npx @modelcontextprotocol/inspector \
uv \
--directory /path/to/mcp-agent/examples/mcp_agent_server/asyncio \
...

gen_client 함수를 사용하여 커스텀 클라이언트를 구축하세요: