RFC Number: 2025-001
Title: Unified MCP Architecture for Frontend and AI Agent Integration
Status: Implemented
Author: Meir Michanie (meirm@cyborg.fi)
Created: August 2025
Last Updated: August 2025
Implementation: Developed with Claude AI assistance
This RFC proposes a unified architecture using the Model Context Protocol (MCP) as a common interface layer between backend services and multiple client types (web frontends and AI agents). This approach eliminates the need for maintaining separate APIs for human and AI interfaces, ensuring feature parity and consistent behavior across all interaction modalities.
Modern applications increasingly require both traditional user interfaces and AI agent interactions. Currently, most architectures maintain separate interfaces:
- REST/GraphQL APIs for web/mobile frontends
- Function definitions or tool specifications for AI agents
- Different validation, error handling, and documentation approaches
This duplication leads to:
- Inconsistent behavior between UI and AI interactions
- Increased maintenance burden
- Feature drift between interfaces
- Complex synchronization requirements
As AI agents become primary interfaces for many users, we need an architecture that treats AI and traditional UI as equal citizens. MCP, originally designed for AI-to-service communication, can serve as a universal protocol for all client types.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Web Browser │ │ OpenWebUI │ │ AI Agent │
│ (React/TS) │ │ (Chat Interface)│ │ (Claude/GPT) │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ HTTP/REST │ HTTP/REST │ MCP
│ │ │
▼ ▼ │
┌─────────────────────────────────────────┐ │
│ MCPO (MCP-to-OpenAPI) │ │
│ Proxy Layer │ │
│ (Port 8003) │ │
└────────────────┬────────────────────────┘ │
│ │
│ MCP (stdio) │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ MCP Server │
│ (stdio transport) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Tools │ │ Resources │ │ Prompts │ │
│ │ (5 tools) │ │ (5 resources)│ │ (4 prompts) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────────────┬───────────────────────────────┘
│
│ HTTP/REST
▼
┌───────────────────────────────────────────────────────────────┐
│ Backend API │
│ (FastAPI - Port 8001) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ SQLite │ │ Task │ │ Analytics │ │
│ │ Database │ │ CRUD │ │ Metrics │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└───────────────────────────────────────────────────────────────┘
- Purpose: Expose business logic through MCP primitives
- Components:
- Tools: 5 executable functions (create, update, delete, search, bulk operations)
- Resources: 5 data access points (task lists, metrics, filtered views)
- Prompts: 4 AI interaction templates (planning, prioritization, standup, sprint)
- Implementation: Python with mcp library, stdio transport
- File:
apps/mcp-server/mcp_server_stdio.py
- Purpose: Translate MCP protocol to OpenAPI REST for web clients and tools
- Features:
- Automatic REST endpoints generated from MCP tools
- OpenAPI/Swagger documentation generation
- API key authentication
- Compatible with OpenWebUI and other OpenAPI tools
- Implementation: Python MCPO package
- File:
apps/mcpo-wrapper/setup_mcpo.py
- Web Frontend: React/TypeScript app consuming MCPO REST endpoints
- OpenWebUI: Chat interface using MCPO OpenAPI integration
- AI Agents: Direct MCP connection via stdio transport
- Third-party: Any HTTP client via MCPO OpenAPI endpoints
The MCP server implementation is located in apps/mcp-server/mcp_server_stdio.py and provides:
# 1. create_task - Create new tasks
# 2. update_task - Update existing tasks
# 3. delete_task - Delete tasks
# 4. search_tasks - Search and filter tasks
# 5. bulk_update_tasks - Update multiple tasks at once# 1. task://list - Paginated task listing
# 2. task://get/{id} - Individual task by ID
# 3. task://metrics - Task analytics and metrics
# 4. task://pending - All pending tasks
# 5. task://completed - All completed tasks# 1. project_planning - Break projects into tasks
# 2. task_prioritization - Analyze task priority
# 3. daily_standup - Generate standup reports
# 4. sprint_planning - Plan development sprintsThe server uses stdio transport for maximum compatibility and connects to the backend API at http://localhost:8001 via HTTP client.
The MCPO proxy layer is implemented using the mcpo package in apps/mcpo-wrapper/setup_mcpo.py:
class MCPOWrapper:
def __init__(self, mcpo_port=8003, backend_url="http://localhost:8001",
api_key="task-management-secret"):
self.mcpo_port = mcpo_port
self.backend_url = backend_url
self.api_key = api_key
def start_mcpo_single(self):
"""Start MCPO with single MCP server"""
cmd = [
sys.executable, "-m", "mcpo",
"--port", str(self.mcpo_port),
"--api-key", self.api_key,
"--",
sys.executable, "../mcp-server/mcp_server_stdio.py"
]
env = os.environ.copy()
env["BACKEND_API_URL"] = self.backend_url
subprocess.run(cmd, env=env, cwd="apps/mcpo-wrapper")Key Features:
- Automatic Endpoint Generation: Creates REST endpoints for each MCP tool
- OpenAPI Documentation: Auto-generated at
http://localhost:8003/docs - Authentication: API key protection for all endpoints
- Tool Mapping: Direct 1:1 mapping from MCP tools to HTTP endpoints
The React frontend connects to MCPO using standard REST API calls. Located in apps/frontend/src/hooks/useMCP.ts:
const API_BASE = process.env.REACT_APP_MCPO_URL || 'http://localhost:8003';
const API_KEY = process.env.REACT_APP_MCPO_API_KEY || 'task-management-secret';
export const useMCP = () => {
const executeTool = useCallback(async (toolName: string, args: any) => {
const { data } = await axios.post(
`${API_BASE}/${toolName}`,
args,
{
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
}
);
return data;
}, []);
return { executeTool };
};Key Changes from Original Design:
- Uses MCPO REST endpoints instead of custom bridge
- Standard HTTP authentication with Bearer tokens
- Simplified error handling and response parsing
- No WebSocket support (MCPO uses standard HTTP)
- Single Source of Truth: Business logic defined once in MCP
- Automatic API Generation: REST endpoints derived from MCP definitions
- Type Safety: End-to-end typing from backend to frontend
- Reduced Duplication: No need for separate AI function definitions
- Feature Parity: UI and AI have identical capabilities
- Consistent Behavior: Same validation and error handling
- Progressive Enhancement: Start with AI, refine with UI
- Unified Monitoring: Single point for logging and metrics
- Seamless Handoff: Users can switch between AI and UI
- Consistent Mental Model: Same operations available everywhere
- AI-Assisted UI: AI can guide users through complex UI workflows
- ✅ MCP Server: Implemented with 5 tools, 5 resources, 4 prompts
- ✅ MCPO Proxy: Using standard MCPO package for OpenAPI bridge
- ✅ React Frontend: Complete TaskManager with MCPO integration
- ✅ AI Integration: Tested with Claude via direct MCP and OpenWebUI via MCPO
- MCPO over Custom Bridge: Used proven MCPO package instead of custom HTTP bridge
- Stdio Transport: MCP server uses stdio for maximum compatibility
- API Key Authentication: Simple Bearer token auth via MCPO
- Standard REST: Frontend uses standard HTTP/REST instead of WebSocket
- Proven Components: Uses established MCPO package and MCP libraries
- OpenWebUI Ready: Direct integration with OpenWebUI and other tools
- Simple Deployment: 4 separate components, easy to containerize
- Standard Protocols: HTTP REST for web, MCP for AI, no custom protocols
- MCPO Authentication: API key-based authentication (
task-management-secret) - MCP Server: No authentication required (protected by MCPO layer)
- Backend API: No authentication (internal component)
- Frontend: Uses MCPO API key for all requests
- Use environment variables for API keys (not hardcoded secrets)
- Implement proper user authentication and session management
- Add rate limiting at MCPO or reverse proxy layer
- Use HTTPS/TLS in production deployments
- Consider OAuth2 or JWT tokens for user authentication
- MCP Server: Validates all tool arguments via JSON schemas
- Backend API: Pydantic models validate request/response data
- MCPO: Inherits MCP validation and adds HTTP-specific validation
- ✅ Unified Interface: Same task operations available in web UI and AI chat
- ✅ Standard Protocols: MCPO provides standard OpenAPI REST endpoints
- ✅ Feature Parity: AI and UI have identical capabilities through MCP layer
- ✅ Easy Integration: OpenWebUI and other tools work out of the box
- ✅ Strong Validation: JSON schemas prevent invalid operations
- ✅ Simple Architecture: 4 clear components with well-defined interfaces
- Additional Latency: MCPO adds ~20ms overhead for web requests
- Component Complexity: 4 separate services to deploy and monitor
- API Key Management: Simple but requires secure key distribution
- Limited Customization: MCPO provides standard REST, less flexibility than custom bridge
- MCPO Maturity: MCPO package is stable and production-ready
- Stdio Reliability: MCP stdio transport is more reliable than HTTP for process communication
- OpenWebUI Integration: Works seamlessly with standard OpenAPI tools
- Development Speed: Using proven components significantly faster than custom development
- ✅ HTTP Bridge: MCPO provides mature, proven OpenAPI bridge solution
- ✅ Authentication: API key authentication via MCPO is sufficient for MVP
- ✅ Tool Integration: OpenWebUI integration works seamlessly with MCPO
- ✅ Transport Protocol: stdio transport is more reliable than HTTP for MCP
- Multi-Server Federation: MCPO supports multiple MCP servers in single deployment
- Advanced Authentication: OAuth2/JWT integration for production user management
- Caching Layer: Redis caching for MCP resources and frequent operations
- Monitoring: Metrics and observability for all 4 components
- WebSocket Support: Real-time updates for task status changes
- Model Context Protocol Specification
- MCP Python SDK
- MCPO Package - MCP to OpenAPI Proxy
- OpenWebUI - AI Chat Interface with OpenAPI Tools
# Terminal 1: Backend API
cd apps/backend && python main.py
# Terminal 2: MCPO Proxy
cd apps/mcpo-wrapper && python setup_mcpo.py --port 8003
# Terminal 3: Frontend (optional)
cd apps/frontend && npm start# Build all services
docker-compose build
# Start the stack
docker-compose up -d
# Access points:
# - Backend API: http://localhost:8001
# - MCPO OpenAPI: http://localhost:8003/docs
# - Frontend: http://localhost:3000The unified MCP architecture has been successfully implemented and demonstrates the viability of treating AI agents and traditional UIs as equal citizens. Key achievements:
- ✅ Proven Architecture: 4-component system with clear separation of concerns
- ✅ Standard Interfaces: OpenAPI REST for web tools, MCP for AI agents
- ✅ Feature Parity: Identical task operations available across all interfaces
- ✅ Production Ready: Uses mature components (MCPO, MCP SDK, FastAPI)
This architecture provides a solid foundation for AI-native applications requiring both traditional web interfaces and AI agent integration. The use of proven components like MCPO significantly reduces development complexity while providing robust, standards-based interfaces.
Development Notes: This implementation was developed through collaborative work with Claude AI, demonstrating effective human-AI collaboration in software architecture and development. The iterative design process, from initial RFC through final implementation, showcases how AI assistance can accelerate complex system development while maintaining high code quality and architectural coherence.