# @tanstack/ai-mcp-sandbox
Per-tool sandboxing for `@tanstack/ai-mcp`. Serve a tool whose body is an
**untrusted snippet** running inside a Code Mode isolate, capability-scoped per
caller by a signed manifest.
## Why
`createMCPServer` authenticates the caller and then trusts the tool code. That
is right for first-party tools. It is not enough when the tool code is something
the operator did not write (installed/third-party tools, an "app store" for a
pod). This package adds the missing execution layer: a tool backed by a snippet
that runs in an isolate and touches the host only through narrow, typed
**facades** — so a tool you do not fully trust can be served safely.
Sandboxing is a property of an **individual tool**. A `createMCPServer` tool
list can freely mix plain in-process tools and sandboxed, snippet-backed tools.
## How it works
`sandboxedTool()` returns a plain `ServerTool`, so it drops straight into
`createMCPServer({ tools: [...] })`. Per call it:
1. Reads `ctx.context.authInfo` and checks the manifest's required **scope**
against the caller's token (the server's `requiredScopes` is too coarse).
2. Builds the **capability set** — the manifest's declared facades, narrowed by
an optional per-client policy.
3. Runs the snippet on any Code Mode `IsolateDriver` with only those facade
bindings, under `min(manifest.limits, serverCaps)` (wall clock, memory,
injected-call count, result size).
4. Shapes the result (author-declared truncation + size cap) and emits an audit
record.
It is driver-agnostic — pass `@tanstack/ai-isolate-quickjs` (portable),
`@tanstack/ai-isolate-node` (V8), or any other `IsolateDriver`.
## Example
```ts
import { toolDefinition } from '@tanstack/ai'
import { createMCPServer } from '@tanstack/ai-mcp/server'
import { sandboxedTool } from '@tanstack/ai-mcp-sandbox'
import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
const driver = createQuickJSIsolateDriver()
// Host-side facade: secrets and backend URLs live here, never in the isolate.
const facades = {
'http.get': {
description: 'GET an allowlisted URL',
execute: async (args: unknown) => {
if (typeof args !== 'object' || args === null || !('url' in args)) {
throw new Error('url is required')
}
return (await fetch(String(args.url))).text()
},
},
}
// Snippet is already-transpiled JS. Its SHA-256 must equal manifest.snippetHash.
const snippet = `
const body = await host.http.get({ url: input.url })
return { length: body.length }
`
const fetchLength = sandboxedTool({
manifest: {
name: 'fetch_length',
version: '1.0.0',
tier: 1,
scope: 'web:read',
inject: ['http.get'],
limits: {
wallClockMs: 5000,
memoryMb: 64,
maxInjectedCalls: 3,
resultBytes: 16384,
},
truncatable: [],
inputSchema: { type: 'object', properties: { url: { type: 'string' } } },
description: 'Fetch a URL and return its length',
snippetHash: '',
},
snippet,
facades,
driver,
})
export const server = createMCPServer({
name: 'demo',
version: '1.0.0',
tools: [fetchLength], // mix freely with plain tools
})
```
## Manifest signing (optional)
The manifest is the security contract. `signature` (Ed25519 over the canonical
manifest) is **optional** in the format — ceremony for first-party tools in a
repo. Make it mandatory by policy when a registry is writable by anyone but the
operator: pass `publicKey` + `requireSignature: true` to `sandboxedTool()`.
## Importer
`importSnippet()` (and the `tanstack-ai-sandbox-import` CLI) turn a plain Code
Mode snippet into a **deny-by-default, unreviewed** manifest (no injections,
tightest limits, Tier 1). The tool is refused at build time until a human fills
the security fields. Authoring-time only — never a runtime path.
## Approval
Approval never happens inside the isolate. For lasting (Tier-3) writes served to
a foreign MCP host, use `createApprovalStore()` for a host-agnostic two-phase
proposal (`propose → proposalId → confirm`, 5-minute expiry, hash-bound,
fail-closed).