MCP Counter POC - Code Execution Architecture

Overview

This is a proof-of-concept (POC) demonstrating the "Code execution with MCP" pattern, which enables AI agents to execute JavaScript code on a server to control external applications. This architecture can be used as a foundation for building interactive, agent-controlled applications.

What Does This POC Do?

This POC implements a Model Context Protocol (MCP) server that:

1. Exposes a run_script tool to AI agents (like Claude via Gemini CLI)
2. Executes JavaScript code in a sandboxed environment
3. Controls a web-based counter application via WebSocket
4. Synchronizes execution with frontend animations

MCP Counter POC - Code Execution Architecture

Overview

This is a proof-of-concept (POC) demonstrating the "Code execution with MCP" pattern, which enables AI agents to execute JavaScript code on a server to control external applications. This architecture can be used as a foundation for building interactive, agent-controlled applications.

What Does This POC Do?

This POC implements a Model Context Protocol (MCP) server that:

1. Exposes a run_script tool to AI agents (like Claude via Gemini CLI)
2. Executes JavaScript code in a sandboxed environment
3. Controls a web-based counter application via WebSocket
4. Synchronizes execution with frontend animations

Key Capability: Agent-Controlled UI

An AI agent can write JavaScript code that directly controls the counter displayed in a web browser, with execution paused until animations complete to ensure smooth user experience.

Architecture

graph TD
    User[User Mobile/Desktop] -->|HTTPS| Vercel[Vercel Frontend]
    Vercel -->|WebSocket| Tunnel[Localtunnel URL]
    Tunnel -->|Tunnel| LocalServer[Local Server :3000]
    LocalServer -->|MCP| Agent[AI Agent (Gemini)]
    LocalServer -->|Sandbox| VM[VM Context]

Components

1. server.js - MCP server with:

   • Express web server (port 3000)
   • WebSocket server for real-time communication
   • MCP server exposing run_script tool
   • VM sandbox for secure code execution

2. index.html - Frontend (Deployed on Vercel) with:

   • Real-time counter display
   • WebSocket client connecting to Localtunnel URL
   • Animation system (3-second delay per update)
   • Pause/Resume controls

3. launcher.js - Launcher for MCP integration

   • Spawns server.js with correct environment
   • Captures error logs for debugging

The "Code Execution with MCP" Pattern

Traditional Approach (Inefficient)

Agent calls: update_count(1)  → Server updates → Frontend shows 1
Agent waits...
Agent calls: update_count(2)  → Server updates → Frontend shows 2
Agent waits...
Agent calls: update_count(3)  → Server updates → Frontend shows 3

Problem: Multiple round-trips to the agent for simple loops.

Code Execution Approach (Efficient)

Agent calls: run_script({
  code: `
    for (let i = 1; i <= 3; i++) {
      await update_count(i);
    }
  `
})

The server executes the entire loop, pausing at each update_count() call until the frontend animation completes.

Benefit: Complex logic runs in a single agent turn, reducing token usage and latency.

How It Works

1. Agent Generates Code

   • Claude (or another LLM) writes JavaScript to accomplish a task
   • Sends code via the run_script MCP tool

2. Server Executes in Sandbox

   • Code runs in a VM context with access to:
     • update_count(n): Updates counter and pauses until frontend confirms
     • console.log(): Captures logs returned to agent
     • setTimeout, Promise: For delays and async operations

3. WebSocket Synchronization

   • Server broadcasts count updates to frontend
   • Frontend displays animation (3-second delay)
   • Frontend sends turn_complete signal when ready
   • Server resumes script execution

4. Agent Receives Result

   • Script logs and execution status returned to agent
   • Agent can continue with next actions

Setup & Usage

1. Installation

npm install

2. Backend & MCP Setup

1. Start the local backend:

   node server.js
   

2. Configure Gemini (.gemini/settings.json):

   {
     "mcpServers": {
       "pm-jarvis": {
         "command": "node",
         "args": ["C:\\path\\to\\project\\launcher.js"]
       }
     }
   }
   

3. Mobile Access (Localtunnel)

To access the app from a mobile device, expose your local backend:

npx localtunnel --port 3000

• Copy the URL (e.g., https://example.loca.lt).
• Important: Visit this URL in your browser first and enter your IP as the password.

4. Frontend (Vercel)

1. Deploy to Vercel:

   vercel deploy --prod
   

2. Open the Vercel URL on your device.
3. Go to Settings and enter your Localtunnel URL.

Use Cases as Base Architecture

This POC can be adapted for:

1. Agent-Controlled Dashboards

• Replace counter with charts/graphs
• Agent updates visualizations based on data analysis

2. Interactive Forms & Workflows

• Agent fills forms step-by-step
• Validates inputs and handles errors

3. Real-time Notifications

• Agent processes events and updates UI
• Users see live status without polling

4. Game Controllers

• Agent plays games by executing move sequences
• UI updates reflect game state

5. IoT Device Control

• Replace WebSocket frontend with IoT devices
• Agent sends control sequences to hardware

License

MIT

References

• Anthropic: Code execution with MCP
• Model Context Protocol Documentation