mcp-v8: V8 JavaScript MCP Server

What is mcp-v8?

mcp-v8 is a Model Context Protocol server, written in Rust, that lets an AI agent run JavaScript and TypeScript in a sandboxed V8 isolate. Instead of wiring up dozens of narrow tools, it gives the agent one tool—run_js—and the agent writes code that can loop, branch, transform data, and call other tools. It is designed for AI agents that need a flexible, stateful code execution environment.

How to use mcp-v8?

Install the server via the provided curl script (install.sh) or use nix run, Docker, or build from source. Connect an MCP client by adding mcp-v8 with flags like --stateless or --directory-path to the client's mcpServers configuration. The server can also run over HTTP using mcp-v8 --stateless --http-port 8080. Configuration can be done entirely through CLI flags or a single TOML/JSON config file.

Key features of mcp-v8

• One run_js tool that executes JavaScript/TypeScript in an isolated V8 engine.
• Async execution model with execution IDs, polling, and cancellation.
• Content-addressed heap snapshots for persistent state across calls (local FS, S3, or cache).
• Policy-gated capabilities: fetch, filesystem, subprocess, and external imports controlled via OPA/Rego.
• Multiple transports: stdio, Streamable HTTP, legacy HTTP+SSE, plus a REST sidecar.
• JWKS authentication and optional Raft clustering for horizontal scaling.
• MCP tasks support for long-running executions (SEP-1319).

Use cases of mcp-v8

• AI agents performing complex data transformations that require looping and branching.
• Building stateful multi-turn workflows where variables and objects persist across calls.
• Running custom JavaScript or TypeScript scripts fetched from the server filesystem.
• Composing multiple MCP servers by calling upstream tools from within the sandboxed code.
• Long-running background computations with async polling and cancellation via tasks.

FAQ from mcp-v8

What is the difference between stateful and stateless mode?

In stateful mode, the V8 heap is saved as a content-addressed snapshot after each run, allowing an agent to build up state across many turns. In stateless mode no heap is persisted—the script runs and returns output immediately.

Which capabilities are gated by default?

Network requests (fetch), filesystem access (fs.*), subprocess execution (child_process), and external ES module imports are all off by default. They must be explicitly enabled via OPA/Rego policies.

What are the main limitations of mcp-v8?

setInterval is not available (use a loop with setTimeout). There is no DOM or browser APIs. TypeScript is type-stripped but not type-checked, and JSX/TSX is not supported.

How do I configure policies for fetch, filesystem, or subprocess?

Policies are set via CLI flags (e.g., --policy-fetch, --policy-fs, --policy-subprocess) that point to Rego policy files, or through the corresponding sections in a TOML/JSON config file.

Does mcp-v8 support long-running executions as MCP tasks?

Yes, the server natively implements the MCP tasks utility over Streamable HTTP and stdio. A client can run run_js as a task by adding a task object to the request, then poll with tasks/get and tasks/result.