Claude Agentic Workflow: Practice of MCP Agent Architecture Based on React and Python

This project demonstrates how to build a modern Claude MCP agent workflow system using a decoupled architecture with React frontend and FastAPI backend, supporting session context management and real-time dialogue interaction.

As Anthropic's Model Context Protocol (MCP) gradually becomes the standard protocol for interaction between AI assistants and external tools, the developer community has begun to explore how to build more flexible and scalable agent workflow systems. The traditional single-interface model is being replaced by modern decoupled front-end and back-end architectures, and the Claude-Agentic-Workflow project is a typical representative of this trend.

The project uses a clear layered architecture to decouple the user interaction layer from the agent logic layer:

The backend is built on Python's FastAPI framework, with the core module app/api.py encapsulating the business logic of MCPAgent. Compared to the early Streamlit prototype, this architecture offers significant advantages:

• Standardized API: Exposes agent capabilities via RESTful interfaces for easy third-party integration
• Session State Management: Each conversation session has independent context storage to ensure coherence in multi-turn dialogues
• Asynchronous Processing: FastAPI natively supports asynchronous operations, enabling efficient handling of concurrent requests

The backend provides three core endpoints:

• GET /health: Service health check
• POST /api/chat: Dialogue message processing
• POST /api/reset: Session context reset

The frontend uses React 18 with the Vite build tool, replacing Streamlit or Gradio commonly used in traditional Python web applications. This choice brings a smoother user experience and richer interaction possibilities:

• Component-Based Architecture: Chat interfaces, message bubbles, input boxes, and other elements can be developed and reused independently
• State Management: React's Hooks mechanism keeps frontend state synchronized with backend session state
• Real-Time Feedback: Supports modern chat experiences like typewriter effects and streaming message rendering

The core value of this project lies in the complete implementation of the MCP (Model Context Protocol) protocol. MCP defines communication specifications between AI assistants and external tools, data sources, and execution environments, enabling models like Claude to:

Through MCP, the system can dynamically discover available tool sets (such as file operations, API calls, code execution, etc.) and intelligently select appropriate tools based on dialogue context. The MCPAgent.run_agent() method encapsulates this decision-making process; each user input triggers a complete cycle of:

• Intent understanding
• Tool selection
• Parameter filling
• Execution invocation
• Result integration

Context retention in multi-turn dialogues is a key challenge for agent systems. This project addresses this issue through backend session storage:

• Each message is associated with a specific session ID
• Historical messages are organized in chronological order, supporting sliding window truncation
• The context reset function allows users to start a new dialogue thread at any time