Sandboxed execution

Data Tool handlers run inside V8 isolates that the platform provisions per execution. This guide covers what the sandbox provides, what it forbids, and how to design handlers that operate cleanly within the constraints.

What runs where

The MCP server receives a tool call, validates against the schema, runs the handler in a V8 sandbox with env.secrets injected, and reaches external APIs only on the allowed-domains list.

The sandbox is a fresh V8 isolate per call. There is no state shared across invocations and no shared filesystem. Each handler call is independent.

What the sandbox provides

Capability	Description
`fetch()`	Outbound HTTP, restricted to the Data Tool’s allowed domains
`console.log` / `console.warn` / `console.error`	Available, but the output is discarded after each call. To surface a problem, throw an error with a useful message
Standard JavaScript runtime (V8)	ES2022 syntax, async/await, Promises, JSON, etc.
`env.secrets`	A map of placeholders for the secrets configured on the Data Tool (see Secrets)
`env.organizationId`, `env.projectId`	Tenant identifiers for the request

The handler signature is always:

handler: async (props, env) => {
  // props is the validated input
  // env is the runtime environment
  return /* output matching the data component's `output` schema */;
}

What the sandbox forbids

Forbidden	Why
Filesystem access	No isolation between tools otherwise
Process environment variables	Use `env.secrets` instead
Network requests to non-allowed domains	Closes the credential exfiltration path
Cross-tenant data	Each invocation runs as the caller’s project only
Long-running execution (> 60 s default)	Prevents runaway handlers from blocking the platform
Memory beyond the limit (128 MB default)	Prevents memory exhaustion
Native modules / require	Pure JavaScript only

Most of these are obvious from a security standpoint. The execution time and memory limits are platform stability. Work that needs longer than 60 seconds should be split, for example into one tool that starts a job and another that checks on it.

Secrets

Secrets are scoped to the Data Tool, not the project. Different tools can hold different keys — a Stripe key on one tool, a SendGrid key on another. Secrets are encrypted at rest via AWS KMS and never enter the sandbox. Inside the handler, env.secrets.<NAME> is a placeholder string generated for each call. The platform swaps in the real value only in the URL, header values, and string body of an outbound fetch sent over HTTPS, and only to the secret’s bound host when one is set. Code that transforms the value first, such as base64-encoding it for Basic auth or computing an HMAC, works on the placeholder instead.

handler: async (props, env) => {
  const apiKey = env.secrets.STRIPE_API_KEY;
  if (!apiKey) {
    throw new Error("STRIPE_API_KEY secret not configured");
  }

  const res = await fetch("https://api.stripe.com/v1/charges", {
    headers: { Authorization: `Bearer ${apiKey}` }
  });

  return res.json();
}

Metabind Studio never returns secret values in API responses. After a secret is set, only the secret’s name is visible in the UI; the value can only be replaced, not read.

Allowed domains

The sandbox restricts outbound HTTP to the domains listed on the Data Tool. A handler that tries to fetch from a domain not on the list fails before the request leaves the sandbox. Configure allowed domains on the Data Tool:

api.example.com
api-secondary.example.com

Wildcards are not currently supported — list each domain explicitly. Subdomains are matched by host string. This rule closes a class of credential-leak vectors: even if a handler’s logic is buggy and tries to send a token to an attacker-controlled URL, the request fails because the URL isn’t on the allowlist.

Execution limits

Default limits per invocation:

Limit	Default	Notes
Execution time	60 seconds	Hard ceiling. Handlers that exceed are terminated.
Memory	128 MB	Hard ceiling. Handlers that exceed are terminated.
Outbound HTTP requests	50	Further `fetch` calls in the same invocation throw.
Outbound HTTP body size	1 MB request, 5 MB response	Responses are buffered; `fetch` responses provide `text()` and `json()` only.

Task support

Data Tools run synchronously, within the 60-second limit. A Data Tool’s settings include Task Support, but the MCP server doesn’t run MCP tasks yet, so leave it on forbidden, the default. With optional or required, the tool advertises task support that hosts can’t use.

Designing for the sandbox

A few principles that come up in practice:

Treat each call as cold. No caching across invocations inside the handler. Cache externally if you need to.
Fail fast. Validate that secrets exist at the top of the handler. Throw with a useful message — the model sees the error and can adjust.
Use small, focused handlers. A Data Tool that does one thing well is easier to reason about than one that branches across many APIs.
Keep responses small. fetch buffers the whole response, up to 5 MB.

Debugging

When a handler fails:

The error returns to the test panel, or to the model, which can retry.
The call appears under Analytics → Recent Executions in Metabind Studio, with its status, error type, and a short snippet of its input, on the Developer plan and up.

console.log output isn’t kept, so put what you need to know in the error message.

Build a Data Tool

The end-to-end Data Tool walkthrough.

Governance

Where sandboxed execution fits in the broader governance model.

Testing tools

Run a Data Tool in Metabind Studio before you publish.

BindJS Reference

defineDataSource and the property system.

Getting Started

Core Concepts

Building Your MCP App

Publishing

Connecting to MCP Hosts

Assistant SDK

Operations

Sample Apps

Sandboxed execution

What runs where

What the sandbox provides

What the sandbox forbids

Secrets

Allowed domains

Execution limits

Task support

Designing for the sandbox

Debugging

Build a Data Tool

Governance

Testing tools

BindJS Reference

​What runs where

​What the sandbox provides

​What the sandbox forbids

​Secrets

​Allowed domains

​Execution limits

​Task support

​Designing for the sandbox

​Debugging

​Related

Build a Data Tool

Governance

Testing tools

BindJS Reference

What runs where

What the sandbox provides

What the sandbox forbids

Secrets

Allowed domains

Execution limits

Task support

Designing for the sandbox

Debugging

Related