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