ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use Three.js with MCP

Build a Three.js MCP App, connect AI tools to a live scene, and choose the right host, bridge, and React Three Fiber setup.

By the ScreenshotNeo team1 October 20268 min read

Short answer: You can use Three.js with MCP in three different ways: render a scene inside an MCP App, ask an MCP server for Three.js documentation, or connect an MCP client to an already-running browser scene. Start with the official MCP Apps Three.js example when you want an embedded interactive view. Use a browser bridge such as threejs-devtools-mcp or r3f-mcp when an AI tool must inspect or modify your own live project.

1. Choose the Three.js and MCP architecture

Goal Recommended path Host or runtime requirement
Show a generated Three.js scene in an AI conversation Official MCP Apps Three.js example An MCP Apps-compatible host such as basic-host
Get Three.js API explanations and examples The example’s learn_threejs tool Any host that can call the server; embedded UI still needs MCP Apps support
Inspect or edit a running vanilla Three.js scene threejs-devtools-mcp A browser tab running your app and its WebSocket bridge
Inspect or edit a React Three Fiber scene r3f-mcp MCPProvider inside <Canvas>, a local WebSocket server, and an MCP client

MCP connects an AI client to tools exposed by an MCP server. Three.js remains the renderer. The official example renders an MCP App; the community projects bridge calls into a scene that already runs in a browser. These are different integration models, so a client that supports ordinary tool calls may not display an embedded app.

2. Run the official MCP Apps Three.js example

The official example documents both Streamable HTTP and stdio startup. Its sample client configuration launches the Three.js server through npx with --stdio. Install the repository dependencies first, then choose a transport.

Install and start

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install

# Streamable HTTP
npm run start:http

# Or stdio
npm run start:stdio

Open the result in basic-host or another MCP Apps-compatible host. A plain MCP client may list and call tools but have no surface in which to render the embedded Three.js interface.

Configure a stdio MCP client

{
  "mcpServers": {
    "threejs": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-threejs",
        "--stdio"
      ]
    }
  }
}

Use the configuration format required by your client. The important details from the example are the npx command and the --stdio argument; client configuration file locations differ.

What the example provides

  • show_threejs_scene for displaying a Three.js visualization.
  • learn_threejs for Three.js API documentation and code examples.
  • Interactive rendering, streaming code preview, and helpers such as OrbitControls, bloom post-processing, and render passes.

The sample scene uses a THREE.Scene, a PerspectiveCamera, a WebGLRenderer, a cube mesh, a floor, lights, and an animation loop. Treat the repository README as the source of current package and host instructions.

3. Understand the render and tool flow

A typical embedded-app request follows this path:

  1. The AI client sends an MCP tool call.
  2. The MCP server prepares scene code or scene data.
  3. The MCP Apps host creates the embedded app surface.
  4. Three.js initializes the renderer, camera, lights, and animation loop.
  5. The host streams the rendered result and any code preview back into the conversation.

This explains why host compatibility matters. The server can expose tools successfully while the UI fails to appear if the client does not implement MCP Apps rendering.

4. Ask MCP for Three.js documentation

The official example’s learn_threejs tool is useful when an agent needs API material while constructing a scene. A practical request should name the concept and the version or constraints you care about:

Explain how to create a PerspectiveCamera for a 16:9 canvas.
Include near and far clipping planes, camera positioning, and a resize handler.

Use the returned material as generated guidance, then check the Three.js version used by your project. The MCP example documents this tool as part of its server; it is not a guarantee that every unrelated MCP server exposes it.

5. Connect MCP to an existing vanilla Three.js scene

If you already have a development server and browser scene, threejs-devtools-mcp describes a live browser-bridge pattern. Its README covers scene inspection and modification of objects, materials, shaders, textures, animations, performance, and memory diagnostics.

Setup checklist

  1. Add the repository’s MCP server configuration to your client (the README lists Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, and OpenCode examples).
  2. Start your Three.js development server.
  3. Open the application in a browser tab where the bridge is injected.
  4. Keep that tab open while the MCP server communicates with the scene over WebSocket.
  5. Use the client’s tools to inspect or modify the live scene.

This is not the embedded MCP Apps renderer. The browser tab is the runtime that owns your scene, and the bridge forwards tool calls to it. If the tab closes or the development server changes its origin, the connection can disappear.

6. Connect MCP to React Three Fiber

For React Three Fiber, the r3f-mcp repository documents a provider-based integration. The provider runs inside the R3F canvas; a separate server exposes MCP over stdio and connects to the scene over localhost WebSocket.

Install and add the provider

npm install r3f-mcp
import { Canvas } from '@react-three/fiber'
import { MCPProvider } from 'r3f-mcp'

export default function App() {
  return (
    <Canvas>
      <MCPProvider>
        {/* Name important objects so tools can find them. */}
        <mesh name="heroCube" position={[0, 0, 0]}>
          <boxGeometry args={[1, 1, 1]} />
          <meshStandardMaterial color="orange" />
        </mesh>
      </MCPProvider>
    </Canvas>
  )
}

Start the bridge server

npx r3f-mcp-server --port 3333

Configure your AI client to run that server according to the repository README. The documented architecture is MCP stdio between client and server, plus localhost WebSocket between the server and MCPProvider. Name scene objects explicitly; the repository recommends this for reliable lookup. Its README describes scene-graph inspection, mutations, spatial queries, screenshots, and component injection. Attribute those capabilities to the repository and verify compatibility before adopting them.

7. Design prompts and scene data for reliable tool use

  • Use stable names such as heroCube, mainLight, and ground.
  • Ask for one mutation at a time, then inspect the result.
  • State coordinate units, target object, and desired transform explicitly.
  • Keep a reset action in your app so experiments are reversible.
  • Expose only the scene operations your team is comfortable allowing an agent to call.

These practices reduce ambiguity in any bridge architecture. They do not replace access controls or project-specific validation.

8. Troubleshooting

Symptom Likely cause Fix
Tools appear, but no 3D view renders The client does not support MCP Apps UI Use basic-host or another MCP Apps-compatible host for the official example.
npx process exits immediately Wrong package, missing dependency, or missing --stdio Follow the example’s current README, reinstall dependencies, and verify the exact stdio arguments.
Live-scene tools cannot find objects The browser bridge is not connected or objects lack stable names Keep the browser tab open, check the WebSocket connection, and add explicit object names.
R3F server runs but sees no scene MCPProvider is outside Canvas or the port differs Place the provider inside <Canvas> and make the configured port match --port 3333.
Changes vanish after reload The agent mutated runtime state only Persist approved changes in source code or project data after inspecting them.
Scene is slow or blank Renderer initialization, asset loading, or an exception in generated code Check browser developer-console errors, confirm assets resolve, and reduce the scene to a camera, light, and one mesh before adding effects.

9. Performance, reliability, and security considerations

  • Rendering: post-processing, high-resolution textures, and large geometry increase GPU and transfer cost. Start with a simple scene and add effects incrementally.
  • Bridge reliability: live browser integrations depend on the development server, an open tab, and a WebSocket path. Reconnect after reloads and origin changes.
  • Transport: the official example documents stdio and Streamable HTTP. Pick the transport your host supports and follow its process-lifecycle rules.
  • Isolation: generated JavaScript and scene mutations can affect your development app. Use a disposable project or review tool calls before allowing destructive operations.
  • Version drift: package names, host support, and repository instructions can change. Check the current project documentation when you implement.

10. Capture an MCP or Three.js scene without browser setup

If your goal is a dependable image or PDF of a page that contains a Three.js scene, you can call ScreenshotNeo instead of maintaining a capture browser. Its API accepts one GET request and returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for the complete option list.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

For a Three.js page, replace the example URL with your deployed scene URL. ScreenshotNeo can wait for a selector, delay, or network idle; load lazy images for full-page captures; run custom JavaScript or CSS; click an element; set a viewport, device preset, retina scale, timezone, geolocation, headers, cookies, user agent, or Authorization; block ads, trackers, requests, or resource types; capture an element; resize output; cache with a chosen TTL; create signed links; submit async jobs with signed webhooks; capture up to 100 URLs per bulk call; and return PDFs with paper size, margins, orientation, and page ranges.

Cookie and consent banners, newsletter popups, and chat widgets are accepted or removed before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; inspect X-Page-Verdict and X-Billed in responses. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

11. FAQ

Can any MCP client display the official Three.js app?

No. The example requires an MCP Apps-compatible host for its embedded UI. A client that only supports tool calls may still call tools but cannot render the app surface.

Is a browser bridge the same as an MCP App?

No. An MCP App renders inside a compatible host. A bridge connects MCP calls to a scene already running in a browser, usually over WebSocket.

Do I need React Three Fiber?

No. The official example and the vanilla devtools bridge use Three.js directly. R3F is a separate option with its own provider and server.

How can an agent identify the right object?

Give important objects stable names and include those names in tool requests. This is especially useful in the R3F provider workflow.

Where should I check for breaking changes?

Check the current README and issues for the official ext-apps example or the community repository you selected, along with your MCP client’s compatibility notes.

Keep reading