Repository navigation
feat(ai-mcp-sandbox): per-tool sandboxing for createMCPServer #2171
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jherr
wants to merge
6
commits into
main
Choose a base branch
from
secure-mcp-server-base-v2
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+1,977
−9
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
b2ca819
feat(ai-mcp-sandbox): per-tool sandboxing for createMCPServer
jherr 9e5a085
ci: apply automated fixes
autofix-ci[bot] 046fc93
fix(ai-mcp-sandbox): address review — prototype-key signing, audit, i…
jherr 935a6e1
fix(ai-mcp-sandbox): address CodeRabbit review
jherr 90d6fbc
fix(mcp-sandbox): harden approval store, audit classification, and docs
jherr e148211
docs(mcp-sandbox): fix kiira type-check on sandboxed-tools snippets
jherr File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| '@tanstack/ai-mcp-sandbox': minor | ||
| --- | ||
|
|
||
| New package: per-tool sandboxing for `@tanstack/ai-mcp`. `sandboxedTool()` | ||
| returns a plain `ServerTool` that runs an untrusted, snippet-backed tool body | ||
| inside any Code Mode `IsolateDriver`, capability-scoped per caller by a signed | ||
| manifest (scope, injected facades, resource limits, optional Ed25519 signature). | ||
| Drops into `createMCPServer({ tools })` alongside trusted tools. Includes a | ||
| two-phase approval store for Tier-3 writes and a deny-by-default snippet | ||
| importer (`importSnippet` + `tanstack-ai-sandbox-import` CLI). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,269 @@ | ||
| --- | ||
| title: Sandboxed Tools | ||
| id: mcp-server-sandboxed-tools | ||
| order: 13 | ||
| description: "Back an MCP tool with an untrusted snippet that runs in an isolate, so you can serve a tool whose code you did not write without giving it your whole process." | ||
| keywords: | ||
| - tanstack ai | ||
| - mcp | ||
| - model context protocol | ||
| - mcp server | ||
| - sandbox | ||
| - isolate | ||
| - sandboxedTool | ||
| - createMCPServer | ||
| - code mode | ||
| --- | ||
|
|
||
| `createMCPServer` runs each tool's `.server()` function in your process, with full access to your files, network, and secrets. That is right for tools you wrote. It is not right for a tool you installed, or one whose code you do not fully trust. | ||
|
|
||
| Back that tool with a snippet that runs in an isolate instead. The snippet reaches the host only through facades you declare, under limits you set, and only for a caller whose token carries the right scope. `sandboxedTool()` returns a normal server tool, so it drops into the same `tools` list next to your plain tools. | ||
|
|
||
| ## Quick setup | ||
|
|
||
| 1. Install the sandbox package and an isolate driver: | ||
|
|
||
| <!-- ::start:tabs variant="package-manager" mode="install" --> | ||
|
|
||
| react: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| vue: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| solid: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| svelte: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| preact: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| angular: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| vanilla: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
| octane: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs | ||
|
|
||
| <!-- ::end:tabs --> | ||
|
|
||
| The driver is swappable. `@tanstack/ai-isolate-quickjs` runs anywhere, including edge runtimes. See [Isolate Drivers](../code-mode/code-mode-isolates) for the others. | ||
|
|
||
| 2. Define the facades. A facade is a host function the snippet may call. Secrets and backend URLs live here, in your process, and never enter the isolate: | ||
|
|
||
| ```ts | ||
| // src/facades.ts | ||
| const ALLOWED = new Set(['https://api.example.com']) | ||
| // Cap the body read into the host process. The isolate limits bound the | ||
| // snippet's heap and result, not what the facade buffers, so an allowed | ||
| // endpoint that returns a huge body could exhaust host memory without this. | ||
| const MAX_BODY_BYTES = 256 * 1024 | ||
|
|
||
| async function readCapped(response: Response, max: number): Promise<string> { | ||
| const body = response.body | ||
| if (!body) return '' | ||
| const reader = body.getReader() | ||
| const chunks: Array<Uint8Array> = [] | ||
| let total = 0 | ||
| try { | ||
| for (;;) { | ||
| const { done, value } = await reader.read() | ||
| if (done) break | ||
| total += value.length | ||
| if (total > max) { | ||
| await reader.cancel() | ||
| throw new Error('response body too large') | ||
| } | ||
| chunks.push(value) | ||
| } | ||
| } finally { | ||
| reader.releaseLock() | ||
| } | ||
| return new TextDecoder().decode( | ||
| chunks.reduce<Uint8Array>((acc, c) => { | ||
| const next = new Uint8Array(acc.length + c.length) | ||
| next.set(acc) | ||
| next.set(c, acc.length) | ||
| return next | ||
| }, new Uint8Array(0)), | ||
| ) | ||
| } | ||
|
|
||
| export 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') | ||
| } | ||
| const url = new URL(String(args.url)) | ||
| if (!ALLOWED.has(url.origin)) throw new Error('origin not allowed') | ||
| // redirect: 'error' stops an allowed origin from bouncing the request to | ||
| // an internal address. Without it, fetch follows the redirect for you. | ||
| const response = await fetch(url, { | ||
| redirect: 'error', | ||
| signal: AbortSignal.timeout(3000), | ||
| }) | ||
| return readCapped(response, MAX_BODY_BYTES) | ||
| }, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| 3. Write the snippet and its manifest, then wrap them. The snippet is plain JavaScript. It reads its input from `input` and calls facades on `host`: | ||
|
|
||
| ```ts group=server-sandboxed-tools | ||
| // src/mcp-server.ts | ||
| import { createMCPServer, jwtVerifier } from '@tanstack/ai-mcp/server' | ||
| import { hashSnippet, sandboxedTool } from '@tanstack/ai-mcp-sandbox' | ||
| import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' | ||
| import type { Manifest } from '@tanstack/ai-mcp-sandbox' | ||
| import { facades } from './facades' | ||
|
|
||
| const driver = createQuickJSIsolateDriver() | ||
|
|
||
| const snippet = ` | ||
| const body = await host.http.get({ url: input.url }) | ||
| return { length: body.length } | ||
| ` | ||
|
|
||
| const manifest = { | ||
| name: 'page_size', | ||
| 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' } }, | ||
| required: ['url'], | ||
| }, | ||
| description: 'Fetch a URL and return its length', | ||
| snippetHash: hashSnippet(snippet), | ||
| } satisfies Manifest | ||
|
|
||
| const pageSize = sandboxedTool({ manifest, snippet, facades, driver }) | ||
|
|
||
| export const server = createMCPServer({ | ||
| name: 'web', | ||
| version: '1.0.0', | ||
| // A sandboxed tool needs a verified caller: the scope gate reads the token's | ||
| // scopes (here, web:read). Without auth there is no caller and the tool | ||
| // throws before the snippet runs. See MCP Server Auth for the full setup. | ||
| auth: { | ||
| verifier: jwtVerifier({ | ||
| jwksUrl: 'https://auth.example.com/.well-known/jwks.json', | ||
| issuer: 'https://auth.example.com/', | ||
| audience: 'https://mcp.example.com/mcp', | ||
| }), | ||
| }, | ||
| tools: [pageSize], // mix freely with plain tools | ||
| }) | ||
| ``` | ||
|
|
||
| The `scope` on the manifest (`web:read`) must be one of the token's scopes, or the caller gets a scope error and the snippet never runs. See [MCP Server Auth](./server-auth) for issuing and verifying those tokens. Serve it from a route the same way as any MCP server. See [Serve Tools over HTTP](./server). | ||
|
|
||
| ## How a call runs | ||
|
|
||
| Each time a host calls the tool, the wrapper: | ||
|
|
||
| 1. Reads the caller's token from `ctx.context.authInfo` and checks that its scopes include the manifest `scope`. A caller without it gets a scope error, and the snippet never runs. This needs [MCP Server Auth](./server-auth); without it, there is no caller to check. | ||
| 2. Builds the capability set: only the facades named in `inject`. A snippet that calls anything else fails inside the isolate. | ||
| 3. Runs the snippet on the driver under the manifest `limits`. The isolate has no files, no network, and no secrets of its own. | ||
| 4. Shapes the result, then returns it to the host. | ||
|
|
||
| The snippet source must match `snippetHash`, so a changed snippet with an unchanged manifest is refused at startup. | ||
|
|
||
| ## Limits | ||
|
|
||
| `limits` is the budget for one run. The wrapper stops a run that goes past any of them: | ||
|
|
||
| - `wallClockMs`: total time for the run. | ||
| - `memoryMb`: isolate heap. | ||
| - `maxInjectedCalls`: how many facade calls the run may make. | ||
| - `resultBytes`: size of the returned result. Over this, the wrapper truncates the paths you list in `truncatable`, then errors if it is still too large. | ||
|
|
||
| To cap every tool on the server, pass `serverCaps`. Each run uses the tighter of the two: | ||
|
|
||
| ```ts group=server-sandboxed-tools | ||
| sandboxedTool({ | ||
| manifest, | ||
| snippet, | ||
| facades, | ||
| driver, | ||
| serverCaps: { wallClockMs: 3000 }, | ||
| }) | ||
| ``` | ||
|
|
||
| ## Per-caller policy | ||
|
|
||
| Limit which facades a caller may use with `policy`. It returns the subset of declared facades allowed for that caller. Value-level rules (which targets, which rows) belong inside the facade, which reads the caller from its `FacadeContext`: | ||
|
|
||
| ```ts group=server-sandboxed-tools | ||
| sandboxedTool({ | ||
| manifest, | ||
| snippet, | ||
| facades, | ||
| driver, | ||
| policy: (authInfo, declared) => | ||
| authInfo.scopes.includes('web:write') ? declared : [], | ||
| }) | ||
| ``` | ||
|
|
||
| ## Sign the manifest | ||
|
|
||
| The manifest is the security contract. For first-party tools in your repo, the snippet hash is enough. When the manifest comes from somewhere you do not control, sign it so a tampered one is rejected. | ||
|
|
||
| Signing uses Ed25519. It happens in two separate places. Keep them apart: if the server both signs and verifies, a manifest tampered with before signing gets a fresh, valid signature, and verification can no longer catch the change. | ||
|
|
||
| Step one is offline, on a trusted machine. A reviewer checks the manifest, signs it with a private key the server never sees, and keeps that private key protected: | ||
|
|
||
| ```ts | ||
| // sign-manifest.ts — run once, offline, on a trusted machine. The private key | ||
| // stays here and never ships to the server. | ||
| import { signManifest } from '@tanstack/ai-mcp-sandbox' | ||
| import type { Manifest } from '@tanstack/ai-mcp-sandbox' | ||
|
|
||
| // The manifest a reviewer has read and approved by hand. | ||
| declare const reviewedManifest: Manifest | ||
| // privateKey comes from your secret store or an earlier generateManifestKeyPair(). | ||
| declare const privateKey: string | ||
|
|
||
| const signature = signManifest(reviewedManifest, privateKey) | ||
| // Attach `signature` to the manifest you ship, and publish only the matching | ||
| // public key to the server. | ||
| ``` | ||
|
|
||
| Step two is on the server. It loads only the public key and the already-signed manifest, and requires a valid signature. It never holds the private key: | ||
|
|
||
| ```ts group=server-sandboxed-tools | ||
| // The manifest arrives already signed; publicKey is the one matching key the | ||
| // server trusts. The server cannot sign, only verify. | ||
| declare const signedManifest: Manifest | ||
| declare const publicKey: string | ||
|
|
||
| sandboxedTool({ | ||
| manifest: signedManifest, | ||
| snippet, | ||
| facades, | ||
| driver, | ||
| publicKey, | ||
| requireSignature: true, | ||
| }) | ||
| ``` | ||
|
|
||
| `generateManifestKeyPair()` makes the key pair once, during setup, not on every serve. | ||
|
|
||
| ## Import an existing snippet | ||
|
|
||
| Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI: | ||
|
|
||
| ```sh | ||
| npx --package=@tanstack/ai-mcp-sandbox tanstack-ai-sandbox-import ./my-snippet.js | ||
| ``` | ||
|
|
||
| It writes a deny-by-default manifest: a placeholder scope, no facades, the tightest limits, and an `unreviewed` flag. `sandboxedTool()` refuses to serve any manifest that still carries the flag. The flag is the only gate it checks. It does not inspect the scope, facades, or limits, so you must review those yourself and set real values before you remove the flag. This keeps an unreviewed tool from running by accident. | ||
|
|
||
| ## Lasting writes | ||
|
|
||
| A sandboxed tool is a good fit for reads and safe actions. Approval never happens inside the isolate. | ||
|
|
||
| Use a two-phase proposal to put a human decision in front of a write. The first call returns a `proposalId`, and a second call with that id performs the write. `createApprovalStore()` gives you the store: single-use ids, a short expiry, and no surviving proposals after a restart. This works with any MCP host, since it does not rely on a host-side approval prompt. | ||
|
|
||
| A proposal id stops one id from being replayed: consume it once and a second consume of the same id fails. It is not write deduplication. Each `propose()` call mints a new id, so the same action proposed twice yields two ids, and consuming both runs the write twice. For a write that must never run twice, carry a durable idempotency key into the write itself (a unique order id, a row your database rejects on a second insert) so the underlying store refuses the duplicate. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.