This MCP server powers the Generative UI Playground, a demo that combines Static GenUI, MCP Apps, and A2UI to showcase CopilotKit capabilities. The server acts as the MCP Apps backend that serves sandboxed HTML/JS apps for interactive UI experiences (like flight booking or weather cards) and bridges those apps to the frontend UI via the MCP Apps middleware. The setup also includes a Python A2A agent to render declarative A2UI JSON, enabling dynamic UI composition driven by agent responses. Use the three modes—Static GenUI, MCP Apps in iframes, and A2UI—to explore how CopilotKit coordinates UI rendering, tool usage, and human-in-the-loop approval flows across components.

In practice, you can switch between modes in the frontend UI:

• Static GenUI: view pre-built React components such as WeatherCard and StockCard rendered by frontend hooks (useRenderToolCall).
• MCP Apps: launch HTML/JS apps inside sandboxed iframes served by the MCP server (e.g., flight booking, hotel search, trading simulator).
• A2UI: interact with agent-generated declarative JSON UI via the A2UIRenderer to render dynamic forms and lists (e.g., restaurant finder, booking forms).

Tools available include CopilotKitProvider for agent switching, CopilotSidebar for chat-based interactions, and specific hooks like useRenderToolCall and useHumanInTheLoop to display tool results and manage interactive approval flows. The architecture purposefully decouples UI rendering (frontend) from the MCP Apps and A2UI backends, allowing you to prototype rich AI-powered interfaces with clear separation of concerns.

Prerequisites:

• Node.js 18+ (for the MCP server and frontend tooling)
• Python 3.11+ (for the Python A2A agent)
• OpenAI API key (for agent and A2UI rendering)

1. Clone the repository: git clone https://github.com/your-org/generative-ui-playground.git cd generative-ui-playground

2. Install root dependencies (frontend and server tooling):

   From repo root

   npm install

3. Install MCP server dependencies: cd mcp-server npm install

4. Install Python A2A agent: cd ../a2a-agent pip install -e .

5. Prepare environment variables (create a .env file): OPENAI_API_KEY=sk-your-key-here MCP_SERVER_URL=http://localhost:3001/mcp A2A_AGENT_URL=http://localhost:10002

6. Run the services (in separate terminals):

   Terminal 1: MCP Server

   cd mcp-server npm run dev

   Terminal 2: Python A2A Agent

   cd a2a-agent python -m agent

   Terminal 3: Frontend (Next.js)

   npm run dev

7. Open the demo in your browser at http://localhost:3000

Tips and common issues:

• Ensure OpenAI_API_KEY is set in the environment for both the A2UI rendering and agent interactions.
• If the MCP server fails to start, verify that port 3001 is not in use and that dependencies installed correctly (run npm ci to clean install if needed).
• The A2UI workflow relies on the Python A2A agent being reachable at the configured A2A_AGENT_URL; check network accessibility if the UI cannot render declarative JSON.
• When developing locally, you may need to adjust MCP_SERVER_URL and A2A_AGENT_URL in the .env file to match your environment.
• For production, consider securing API keys and using environment-based configuration rather than hardcoding in .env.