mcp-v8 — a JavaScript/TypeScript runtime for AI agents

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, you give the
agent one tool — run_js — and it writes code: looping, branching, transforming
data, and calling other tools, often with far fewer tokens than equivalent
tool-call chains.

In its default stateful mode the V8 heap is saved as a content-addressed
snapshot, so an agent can build up state across many turns. Host capabilities
(network, filesystem, subprocess, WebAssembly, module imports, and calls to other
MCP servers) are all off by default and unlocked only by explicit
OPA/Rego policies.

Why mcp-v8

- One tool, unbounded capability. The agent runs a program, not a fixed menu of tools.
- Durable state. Heap snapshots persist variables and objects across calls.
- Secure by default. fetch, filesystem, subprocess, and external imports are denied until you grant them via policy.
- Production-ready. stdio / Streamable HTTP / SSE transports, a REST sidecar, async execution with pagination, JWKS auth, and Raft-replicated clustering.

Documentation

Full documentation lives at <https://r33drichards.github.io/mcp-js/> (built
from site-docs/) — tutorials, how-to guides, concept
explanations, and complete reference for the CLI flags,
HTTP API, and
MCP tools.

Quick start

Install

# Server
curl -fsSL https://raw.githubusercontent.com/r33drichards/mcp-js/main/install.sh | sudo bash
Optional CLI client
curl -fsSL https://raw.githubusercontent.com/r33drichards/mcp-js/main/install-cli.sh | sudo bash

Installs to /usr/local/bin. Supported platforms: Linux x86_64/arm64 and macOS
Apple Silicon. You can also nix run github:r33drichards/mcp-js, use Docker (see
the docker-compose..yml stacks), or build from source.

# Claude Code (stdio)
claude mcp add mcp-v8 -- mcp-v8 --directory-path /tmp/mcp-v8-heaps   # stateful
claude mcp add mcp-v8 -- mcp-v8 --stateless                          # stateless

{ "mcpServers": { "js": { "command": "mcp-v8", "args": ["--stateless"] } } }

Then ask the agent: "Run this JavaScript: console.log([1,2,3].map(x => x2))".

Run over HTTP

mcp-v8 --stateless --http-port 8080
MCP endpoint: POST http://localhost:8080/mcp
REST sidecar: POST http://localhost:8080/api/exec  (JSON body, or a raw-body file upload)

/api/exec accepts either a JSON body or a raw-body file upload — send the
script as the request body with a non-JSON Content-Type
(curl --data-binary @script.js -H 'Content-Type: application/javascript' .../api/exec).
The run_js MCP tool can also read a script from a path on the server itself
via an optional file parameter — off by default, enabled with
--allow-run-js-file or a run_js_file
policy.

See the Quick Start tutorials and the
transports guide for more.

Configure with a single file

Every flag can also live in one TOML or JSON file passed via --config (or
MCP_V8_CONFIG), including structured sections that replace the separate
WASM / MCP-server / fetch-header / policy JSON files:

# server.toml — run with: mcp-v8 --config server.toml
http_port = 8080
heap_store = "dir"
heap_dir = "/var/lib/mcp-v8/heaps"
[policies.fetch]

policies = [{ url = "file:///etc/mcp-v8/fetch.rego" }]

Precedence is CLI flag > MCP_V8_ env var > config file > default. See the
configuration file reference.

| Global | Purpose | Gated by |
|--------|---------|----------|
| console, setTimeout | Output & timers | — |
| fetch(url, opts?) | HTTP requests (Fetch API) | fetch policy |
| fs. | File I/O (readFile, writeFile, …) | filesystem policy |
| child_process / Deno.Command | Run subprocesses | subprocess policy |
| import (npm: / jsr: / URL) | External ES modules | --allow-external-modules + modules policy |
| WebAssembly, __wasm_<name> | Run/instantiate WASM | — |
| mcp.callTool/listTools/servers | Call upstream MCP servers | mcp_tools policy |

See Concepts → Security policies for the policy model.

MCP tools

…