CodeEx Agent

ReAct Agent + MCP Code Execution - LangChain 기반 MCP 도구 테스트 Web UI

Anthropic의 Code Execution with MCP 패턴을 LangGraph ReAct Agent로 구현한 시스템입니다. MCP 서버 URL을 입력하면 도구를 자동으로 탐색하고, LLM이 Python 코드를 생성하여 실행합니다.

작동 원리

사용자 질문
    |
    v
+------------------------------------------+
|  LangGraph ReAct Agent                   |
|                                          |
|  1. Thought: 어떤 MCP 도구를 쓸지 판단   |
|  2. Action:  Python 코드 생성            |
|  3. Observation: 코드 실행 결과 확인      |
|  4. (반복 또는 최종 답변)                 |
+------------------------------------------+
    |
    v
+------------------------------------------+
|  MCPCodeExecutionTool._run()             |
|                                          |
|  exec(code, {mcp_call: ...})             |
|  - mcp_call(url, tool_name, args)        |
|  - stdout/stderr 캡처                    |
+------------------------------------------+
    |
    v
+------------------------------------------+
|  HTTP MCP Client                         |
|  - Streamable HTTP (/mcp)                |
|  - SSE (/sse, deprecated)                |
+------------------------------------------+

기존 tool calling 방식과 달리, LLM이 직접 코드를 생성하여 실행합니다. mcp_call(url, tool_name, arguments) 함수가 실행 환경에 주입되어 LLM이 자유롭게 MCP 도구를 호출할 수 있습니다.

빠른 시작

1. 설치

uv venv
uv sync

2. 환경 설정

cp .env.example .env
# .env 파일에 API 키 설정

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://openrouter.ai/api/v1   # OpenRouter 사용 시
LLM_MODEL=gpt-4o-mini                           # 모델 선택

3. 실행

# Web UI (포트 8080)
uv run python web_ui.py

# 로컬 테스트 MCP 서버 (포트 8000, 별도 터미널)
uv run python tests/test_mcp_server.py

브라우저에서 http://localhost:8080 접속

Web UI 기능

• MCP URL 입력: 여러 MCP 서버 URL 추가/삭제, 프리셋 버튼
• 도구 자동 탐색: URL 입력 시 서버의 도구 목록 자동 조회
• ReAct 과정 표시: Thought / Action (코드) / Observation 단계별 실시간 표시
• SSE 스트리밍: 중간 과정을 실시간으로 수신

프리셋 MCP 서버

이름	URL	Transport	도구
Local TestServer	http://localhost:8000/mcp	Streamable HTTP	echo, add, greet
DeepWiki	https://mcp.deepwiki.com/mcp	Streamable HTTP	read_wiki_structure, read_wiki_contents, ask_question
Semgrep	https://mcp.semgrep.ai/mcp	Streamable HTTP	security scan 등 8개
Cloudflare Docs	https://docs.mcp.cloudflare.com/sse	SSE	search_cloudflare_documentation, migrate_pages_to_workers_guide
Time Server	https://mcp-time-server.ajz.workers.dev/sse	SSE	get_current_time, convert_time

프로젝트 구조

code_exe_agent/
├── web_ui.py                       # FastAPI Web UI (메인 진입점)
├── src/
│   ├── react_workflow.py           # ReAct Agent 워크플로우
│   ├── agent/
│   │   ├── llm_config.py           # ChatOpenAI 설정 (OpenRouter 호환)
│   │   └── mcp_code_tool.py        # LangChain Tool - 코드 실행 + mcp_call 주입
│   └── generator/
│       └── http_mcp_client.py      # HTTP/SSE MCP 클라이언트
├── tests/
│   └── test_mcp_server.py          # FastMCP 테스트 서버
├── pyproject.toml
├── .env.example
└── .env                            # 환경변수 (API 키 등)

모듈 설명

파일	역할
web_ui.py	FastAPI 서버. HTML UI + /api/react/stream (SSE), /api/mcp/tools 엔드포인트
src/react_workflow.py	ReactCodeExecutionWorkflow - MCP URL 연결, LangGraph ReAct Agent 실행, 단계별 콜백
src/agent/llm_config.py	create_llm() - ChatOpenAI 인스턴스 생성. 환경변수 또는 인자로 설정
src/agent/mcp_code_tool.py	MCPCodeExecutionTool - LangChain BaseTool. exec()로 코드 실행, mcp_call() 주입
src/generator/http_mcp_client.py	HTTPMCPClient - MCP SDK로 도구 목록 조회/실행. Streamable HTTP + SSE 지원
tests/test_mcp_server.py	FastMCP 서버 (echo, add, greet 도구)

코드 실행 방식

기존 README에서 설명한 "Sandbox에서 코드 실행"은 현재 다음과 같이 동작합니다:

# src/agent/mcp_code_tool.py - MCPCodeExecutionTool._run()

def _run(self, code: str) -> str:
    # 1. mcp_call 함수를 실행 환경에 주입
    def mcp_call(url, tool_name, arguments):
        client = self.mcp_clients.get(url)
        return client.call_tool(tool_name, arguments)

    exec_globals = {
        "__builtins__": __builtins__,
        "mcp_call": mcp_call,
    }

    # 2. LLM이 생성한 코드를 exec()로 실행
    with redirect_stdout(capture), redirect_stderr(capture):
        exec(code, exec_globals, exec_locals)

    # 3. stdout 캡처 결과 반환
    return capture.getvalue()

LLM이 생성하는 코드 예시:

result = mcp_call("http://localhost:8000/mcp", "add", {"a": 42, "b": 58})
print(result)

기술 스택

• Agent: LangGraph create_react_agent
• LLM: ChatOpenAI (OpenAI / OpenRouter 호환)
• MCP Client: MCP Python SDK (streamablehttp_client, sse_client)
• Web: FastAPI + SSE Streaming (sse-starlette)
• Test Server: FastMCP
• 패키지 관리: uv

참고

• Anthropic - Code Execution with MCP
• Model Context Protocol
• LangGraph ReAct Agent