ext-apps/examples/threejs-server

Example: Three.js App

Interactive 3D scene renderer using Three.js. Demonstrates streaming code preview and full MCP App integration.

MCP Client Configuration

Add to your MCP client configuration (stdio transport):

{
  "mcpServers": {
    "threejs": {
      "command": "npx",
      "args": [
        "-y",
        "--silent",
        "--registry=https://registry.npmjs.org/",
        "@modelcontextprotocol/server-threejs",
        "--stdio"
      ]
    }
  }
}

Local Development

To test local modifications, use this configuration (replace ~/code/ext-apps with your clone path):

{
  "mcpServers": {
    "threejs": {
      "command": "bash",
      "args": [
        "-c",
        "cd ~/code/ext-apps/examples/threejs-server && npm run build >&2 && node dist/index.js --stdio"
      ]
    }
  }
}

Features

• Interactive 3D Rendering: Execute JavaScript code to create and animate Three.js scenes
• Streaming Preview: See the scene build in real-time as code is being written
• Built-in Helpers: Pre-configured OrbitControls, post-processing effects (bloom), and render passes
• Documentation Tool: learn_threejs provides API docs and code examples on demand

Running

1. Install dependencies:

   npm install
   

2. Build and start the server:

   npm run start:http  # for Streamable HTTP transport
   # OR
   npm run start:stdio  # for stdio transport
   

3. View using the basic-host example or another MCP Apps-compatible host.

Tool Input

To test the example, copy the contents of test-input.json into the tool input field in basic-host.

The test input creates a simple scene with a rotating cube:

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, width / height, 0.1, 100);
camera.position.set(2, 2, 2);

const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setSize(width, height);
renderer.shadowMap.enabled = true;

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(),
  new THREE.MeshStandardMaterial({ color: 0x00ff88 }),
);
cube.castShadow = true;
cube.position.y = 0.5;
scene.add(cube);

const floor = new THREE.Mesh(
  new THREE.PlaneGeometry(5, 5),
  new THREE.MeshStandardMaterial({ color: 0x222233 }),
);
floor.rotation.x = -Math.PI / 2;
floor.receiveShadow = true;
scene.add(floor);

const light = new THREE.DirectionalLight(0xffffff, 2);
light.position.set(3, 5, 3);
light.castShadow = true;
scene.add(light);
scene.add(new THREE.AmbientLight(0x404040));

function animate() {
  requestAnimationFrame(animate);
  cube.rotation.y += 0.01;
  renderer.render(scene, camera);
}
animate();

Available Three.js Globals

When writing custom code, these globals are available:

THREE; // Three.js library
canvas; // Pre-created canvas element
width; // Canvas width
height; // Canvas height
OrbitControls; // Camera controls
EffectComposer; // Post-processing composer
RenderPass; // Render pass
UnrealBloomPass; // Bloom effect

Architecture

Server (server.ts)

Exposes two tools:

• show_threejs_scene - Renders a 3D scene from JavaScript code
• learn_threejs - Returns documentation and code examples for Three.js APIs

Supports Streamable HTTP and stdio transports.

App (src/threejs-app.tsx)

React component that:

• Receives tool inputs via the MCP App SDK
• Displays streaming preview from toolInputsPartial.code as code arrives
• Executes final code from toolInputs.code when complete
• Renders to a pre-created canvas with configurable height

Performance

Visibility-Based Pause

Animation automatically pauses when the view scrolls out of view:

• Uses IntersectionObserver to track visibility (browser-native, no polling)
• Wraps requestAnimationFrame to skip frames when not visible
• Animation loop stops completely → zero CPU usage while hidden
• Queued callbacks resume instantly when scrolled back into view

This is transparent to user code - just use requestAnimationFrame normally.

Transparent Background

Supports alpha transparency for seamless host UI integration:

const renderer = new THREE.WebGLRenderer({
  canvas,
  antialias: true,
  alpha: true,
});
renderer.setClearColor(0x000000, 0); // Fully transparent

This is the default - 3D objects composite directly over the host background.