MCP-JS

Build the WASM module (requires Emscripten)

./examples/sqlite-wasm/build.sh

Prerequisites

• Rust (nightly toolchain recommended)
• (Optional) AWS credentials for S3 storage

Installation

Install mcp-v8 using the provided install script:

curl -fsSL https://raw.githubusercontent.com/r33drichards/mcp-js/main/install.sh | sudo bash

This will automatically download and install the latest release for your platform to /usr/local/bin/mcp-v8 (you may be prompted for your password).

Installing mcp-v8-cli

Install the CLI client separately using install-cli.sh:

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

This installs mcp-v8-cli to /usr/local/bin/mcp-v8-cli.

You can also install the CLI via cargo (once the crate is published to crates.io):

cargo install mcp-v8-client

Or download a pre-built binary directly from the GitHub Releases page.

---

Advanced users: If you prefer to build from source, see the Build from Source section at the end of this document.

Build from Source (Advanced)

If you prefer to build from source instead of using the install script:

Build the Server

cd server
cargo build --release

The built binary will be located at target/release/server. You can use this path in the integration steps above instead of /usr/local/bin/mcp-v8 if desired.

CLI Examples

```bash

Quick Start

After installation, you can run the server directly. Choose one of the following options:

Example Usage

Ask Claude or Cursor: "Run this JavaScript: console.log(1 + 2)"

The agent will: 1. Call run_js with code: "console.log(1 + 2)" → receives execution_id 2. Call get_execution with the execution_id → receives { status: "completed" } 3. Call get_execution_output with the execution_id → receives { data: "3\n", total_lines: 1 }

In stateful mode, get_execution also returns a heap content hash — pass it back in the next run_js call to resume from that state.

Point at a remote server via env var

export MCP_V8_URL=https://my-server.example.com mcp-v8-cli executions list ```

Utility Options

- --print-openapi: Print the OpenAPI JSON specification to stdout and exit. Use this to regenerate openapi.json:

  mcp-v8 --print-openapi > openapi.json
  

Storage Options

• --s3-bucket <bucket>: Use AWS S3 for heap snapshots. Specify the S3 bucket name. (Conflicts with --stateless)
• --cache-dir <path>: Local filesystem cache directory for S3 write-through caching. Reduces latency by caching snapshots locally. (Requires --s3-bucket)
• --directory-path <path>: Use a local directory for heap snapshots. Specify the directory path. (Conflicts with --stateless)
• --stateless: Run in stateless mode - no heap snapshots are saved or loaded. Each JavaScript execution starts with a fresh V8 isolate. (Conflicts with --s3-bucket and --directory-path)

Note: For heap storage, if neither --s3-bucket, --directory-path, nor --stateless is provided, the server defaults to using /tmp/mcp-v8-heaps as the local directory.

Transport Options

• --http-port <port>: Enable Streamable HTTP transport (MCP 2025-03-26+) on the specified port. Serves the MCP endpoint at /mcp and a plain API at /api/exec. If not provided, the server uses stdio transport (default). (Conflicts with --sse-port)
• --sse-port <port>: Enable SSE (Server-Sent Events) transport on the specified port. Exposes /sse for the event stream and /message for client requests. (Conflicts with --http-port)

Cluster Options

These options enable Raft-based clustering for distributed coordination and replicated session logging.

• --cluster-port <port>: Port for the Raft cluster HTTP server. Enables cluster mode when set. (Requires --http-port or --sse-port)
• --node-id <id>: Unique node identifier within the cluster (default: node1).
• --peers <peers>: Comma-separated list of seed peer addresses. Format: id@host:port or host:port. Peers can also join dynamically via POST /raft/join.
• --join <address>: Join an existing cluster by contacting this seed address (host:port). The node registers itself with the cluster leader.
• --advertise-addr <addr>: Advertise address for this node (host:port). Used for peer discovery and write forwarding. Defaults to <node-id>:<cluster-port>.
• --heartbeat-interval <ms>: Raft heartbeat interval in milliseconds (default: 100).
• --election-timeout-min <ms>: Minimum election timeout in milliseconds (default: 300).
• --election-timeout-max <ms>: Maximum election timeout in milliseconds (default: 500).

OPA / Fetch Options

These options enable a policy-gated fetch() function in the JavaScript runtime. When fetch policies are configured via --policies-json, a fetch(url, opts?) global becomes available. fetch() follows the web standard Fetch API — it returns a Promise that resolves to a Response object. If fetch-header rules are configured, matching headers are applied first, then the resulting request is evaluated by policy.

• --fetch-header <RULE>: Inject static headers or dynamic OAuth client-credentials tokens into matching fetch requests. Static format: host=<host>,header=<name>,value=<val>[,methods=GET;POST]. Dynamic format: host=<host>,header=<name>,token_url=<url>,client_id=<id>,client_secret=<secret>[,scope=<scope>][,refresh_buffer_secs=30][,methods=GET;POST]. Can be specified multiple times. Requires fetch to be enabled via --policies-json. See Fetch Header Injection for details.
• --fetch-header-config <PATH>: Path to a JSON file with fetch header injection rules. Each rule uses either a static headers object or a dynamic auth block. Requires fetch to be enabled via --policies-json. See Fetch Header Injection for details.

Example:

mcp-v8 --stateless --http-port 3000 \
  --policies-json '{"fetch":{"policies":[{"url":"http://localhost:8181"}]}}'

WASM Module Options

Pre-load WebAssembly modules that are available as global variables in every JavaScript execution.

• --wasm-module <name>=<path>: Pre-load a .wasm file and expose its exports as a global variable with the given name. Can be specified multiple times for multiple modules.
• --wasm-config <path>: Path to a JSON config file mapping global names to .wasm file paths. Format: {"name": "/path/to/module.wasm", ...}.

Both options can be used together. CLI flags and config file entries are merged; duplicate names cause an error.

Example — CLI flags:

mcp-v8 --stateless --wasm-module math=/path/to/math.wasm --wasm-module crypto=/path/to/crypto.wasm

Example — Config file (wasm-modules.json):

{
  "math": "/path/to/math.wasm",
  "crypto": "/path/to/crypto.wasm"
}

mcp-v8 --stateless --wasm-config wasm-modules.json

After loading, the module exports are available directly in JavaScript:

math.add(21, 21); // → 42

Modules with imports (e.g. WASI modules like SQLite) are also supported. When a module has imports, auto-instantiation is skipped and the compiled WebAssembly.Module is exposed as __wasm_<name>. Your JavaScript code can then instantiate it with the required imports:

// __wasm_sqlite is the compiled WebAssembly.Module
var instance = new WebAssembly.Instance(__wasm_sqlite, {
    wasi_snapshot_preview1: { /* WASI stubs */ },
});
instance.exports.sqlite3_open(/* ... */);

Self-contained modules (no imports) are auto-instantiated as before — their exports are set directly on <name>, and the compiled Module is also available as __wasm_<name>.

See the SQLite WASM example for a complete working example.

Heap Storage Options

You can configure heap storage using the following command line arguments:

• S3: --s3-bucket <bucket>
• Example: mcp-v8 --s3-bucket my-bucket-name
• Requires AWS credentials in your environment.
• Ideal for cloud deployments and sharing state across instances.
• S3 with write-through cache: --s3-bucket <bucket> --cache-dir <path>
• Example: mcp-v8 --s3-bucket my-bucket-name --cache-dir /tmp/mcp-v8-cache
• Reads from local cache first, writes to both local cache and S3.
• Reduces latency for repeated snapshot access.
• Filesystem: --directory-path <path>
• Example: mcp-v8 --directory-path /tmp/mcp-v8-heaps
• Stores heap snapshots locally on disk.
• Ideal for local development and testing.
• Stateless: --stateless
• Example: mcp-v8 --stateless
• No heap persistence - each execution starts fresh.
• Ideal for one-off computations and serverless environments.

Note: Only one storage option can be used at a time. If multiple are provided, the server will return an error.

HTTP API & OpenAPI

When running with --http-port or --sse-port, the server exposes a plain REST API alongside the MCP transport:

The OpenAPI specification is also committed to the repo root as openapi.json.

Regenerating openapi.json

cd server
cargo build --release
./target/release/server --print-openapi > ../openapi.json
cp ../openapi.json ../mcp-v8-client/openapi.json

Allow GET requests to a specific API host

allow if { input.method == "GET" input.url_parsed.host == "api.example.com" startswith(input.url_parsed.path, "/public/") }

The policy input includes:
- `operation`: always `"fetch"`
- `url`: the full URL string
- `method`: HTTP method (e.g. `"GET"`, `"POST"`)
- `headers`: request headers (keys normalized to lowercase)
- `url_parsed`: parsed URL components — `scheme`, `host`, `port`, `path`, `query`

**2. Start the server with fetch policy enabled**

**3. Use `fetch()` in JavaScript**

The response object supports:
- Properties: `.ok`, `.status`, `.statusText`, `.url`, `.redirected`, `.type`, `.bodyUsed`
- Methods: `.text()`, `.json()`, `.clone()` (`.text()` and `.json()` return Promises)
- Headers: `.headers.get(name)`, `.headers.has(name)`, `.headers.entries()`, `.headers.keys()`, `.headers.values()`, `.headers.forEach(fn)`

`fetch()` also accepts an options object:

If the OPA policy denies a request, the Promise returned by fetch() is rejected with an error.

Execution Workflow

Execution differs by transport mode:

Stateful MCP:
1. run_js(code)           → { execution_id }
2. get_execution(id)      → { status: "running" | "completed" | "failed" | "cancelled" | "timed_out", result, error }
3. get_execution_output(id, line_offset, line_limit)  → paginated console output

Stateless MCP:
1. run_js(code)           → { output, error? }

Example:

Stateful MCP:
Call run_js with code: "console.log('hello');"
  → { execution_id: "abc-123" }

Call get_execution with execution_id: "abc-123"
  → { status: "completed" }

Call get_execution_output with execution_id: "abc-123"
  → { data: "hello\n", total_lines: 1 }

Stateless MCP:
Call run_js with code: "console.log('hello');"
  → { output: "hello\n" }

Integration

Importing Packages

You can import npm packages, JSR packages, and URL modules directly in your JavaScript code using ES module import syntax. Packages are fetched from esm.sh at runtime — no npm install or pre-installation step is needed.

npm Packages

Use the npm: prefix followed by the package name and version:

import { camelCase } from "npm:lodash-es@4.17.21";
camelCase("hello world"); // → "helloWorld"

import dayjs from "npm:dayjs@1.11.13";
dayjs("2025-01-15").format("MMMM D, YYYY"); // → "January 15, 2025"

JSR Packages

Use the jsr: prefix for packages from the JSR registry:

import { camelCase } from "jsr:@luca/cases@1.0.0";
camelCase("hello world"); // → "helloWorld"

URL Imports

Import directly from any URL that serves ES modules:

import { pascalCase } from "https://deno.land/x/case/mod.ts";
pascalCase("hello world"); // → "HelloWorld"

How It Works

• npm: specifiers are rewritten to https://esm.sh/<package> URLs
• jsr: specifiers are rewritten to https://esm.sh/jsr/<package> URLs
• https:// and http:// URLs are fetched directly
• Relative imports (e.g., ./utils.js) resolve against the parent module's URL
• TypeScript modules (.ts, .tsx) fetched from URLs are automatically type-stripped before execution

Tips

- Always pin versions (e.g., npm:lodash-es@4.17.21) for reproducible results - Only packages that ship as ES modules are supported — CommonJS-only packages won't work directly, but esm.sh converts many of them automatically - Imports are fetched over the network at runtime, so the first execution may be slower while modules are downloaded - Top-level await is supported, so you can use import() dynamically as well:

  const { default: _ } = await import("npm:lodash-es@4.17.21");
  _.chunk([1, 2, 3, 4, 5], 2); // → [[1, 2], [3, 4], [5]]
  

Single module

mcp-v8 --stateless --wasm-module math=./math.wasm

Multiple modules

mcp-v8 --stateless \ --wasm-module math=./math.wasm \ --wasm-module physics=./physics.wasm

Or use a JSON config file for many modules:

**3. Call exports from JavaScript**

The module's exports are available directly on the global variable:

When multiple modules are loaded, each is its own global:

Stateless vs Stateful Mode