Concepts¶

These pages are explanation — they clarify how mcp-v8 works and why it is designed the way it is. They are for understanding, not step-by-step instructions (see How-to guides for those).

The big picture¶

mcp-v8 turns "call a tool" into "run a program." An agent sends JavaScript or TypeScript to the run_js tool; the server runs it in a sandboxed V8 isolate, can persist the resulting heap, and exposes host capabilities only through explicit, policy-gated bridges. Everything else below is a facet of that idea.

Explanations by feature¶

• Running JavaScript & TypeScript — the V8/deno_core execution model.
• Stateful sessions & heap snapshots — content-addressed state persistence.
• Heap storage backends — durability and sharing trade-offs.
• Asynchronous execution & output — the submit→poll lifecycle.
• Transports: stdio, HTTP, SSE — MCP transports and the REST sidecar.
• Network access with fetch — policy gating and server-side secret injection.
• Filesystem access — opt-in, per-operation file I/O.
• Subprocess execution — the process-spawning security model.
• WebAssembly modules — embedding host WASM as JS globals.
• ES module imports — why imports are off by default.
• Calling upstream MCP servers — mcp-v8 as both server and client.
• Security policies (OPA/Rego) — the unified default-deny policy model.
• Authentication (JWT/JWKS) — the token verification trust model.
• Clustering & replication (Raft) — consensus and replicated state.

See also¶

• Tutorials — learn by doing.
• Reference — the exhaustive facts.