React로 구축한 AI Agent를 사용하여 로컬 Python MCP 서버를 구축했습니다

이 서버는 FastMCP가 포함된 공식 Python MCP SDK를 사용하며, 외부 API 호출을 위해 httpx를 사용합니다. 또한 로컬 stdio 및 Streamable HTTP 전송(transports)을 모두 지원합니다.
**Streamable HTTP 전송 (Streamable HTTP transport)**은 Model Context Protocol (MCP)에서 AI 클라이언트를 원격 서버에 연결하는 데 사용되는 현대적인 통신 방식입니다.
주요 기능 중 하나는 모든 클라이언트-서버 메시징에 대해 하나의 통합된 경로(예: /mcp)를 사용한다는 점입니다.

MCP 서버 실행하기

1. 가상 환경 활성화
   명령 프롬프트(Command Prompt)에서:
   .venv\Scripts\activate

2. 프로젝트 설치
   MCP 서버를 추출한 폴더로 이동한 후(이미 해당 폴더에 있다면 생략), 다음을 실행합니다:
   pip install -e .

3. MCP 서버 시작
   vehicle-mcp 또는 vehicle-mcp --transport streamable-http

mcp = FastMCP(
    name="FuelEconomy.gov",
...

async def fuel_vehicle(self, vehicle_id: int) -> dict[str, Any]:
        payload = await self.client.get_json(
...

AI Agent
그 다음, MCP 서버와 인터페이스할 간단한 React AI Agent를 만들었습니다.
React는 다음의 Python MCP 엔드포인트에 직접 연결됩니다:

http://127.0.0.1:8000/mcp

MCP 클라이언트가 등록되었는지 확인하세요

  const mcp = new McpHttpClient(mcpUrl);
  await mcp.connect();
  const listed = await mcp.listTools();
...

React는 다음과 같이 에이전트 루프(agent loop)를 수행합니다:

• MCP에 연결합니다.
• 사용 가능한 MCP 도구(tools)를 가져옵니다.
• 해당 도구 정의를 Gemini에 보냅니다.
• Gemini가 선택한 도구를 실행합니다.
• MCP 결과를 Gemini에 반환합니다.
• 최종 답변을 표시합니다.

*AI Agent - MCP 통합 - localhost에서 실행 중 *

환경 변수 설정

VITE_GEMINI_API_KEY=your_actual_gemini_key
VITE_GEMINI_MODEL=gemini-2.5-flash
VITE_MCP_URL=http://127.0.0.1:8000/mcp

다음 명령어를 실행하여 의존성(dependency)을 설치한 후 서버를 실행하세요.

npm install
npm run dev

전체 아키텍처 (Overall architecture)

React 채팅 UI (React chat UI)
↓ HTTP
Node.js 에이전트 백엔드 (Node.js agent backend)
├── Gemini API
└── stdio를 통한 MCP 클라이언트 (MCP client over stdio)
↓
Python 차량 MCP 서버 (Python vehicle MCP server)
↓
FuelEconomy.gov