MCP and environment

Environment variables

Use env to bake variables into a newly created sandbox:

{
  "env": {
    "API_HOST": "https://api.example.com",
    "FEATURE_FLAG": "enabled"
  }
}

Environment variables:

are accepted only when creating a chat;
are passed through the queued run and baked into sandbox creation;
are not persisted on the chat or turn;
remain available while that chat uses the sandbox.

Limits:

Limit	Value
Variables	64
Key length	256 bytes
Value length	32 KiB
Total keys and values	128 KiB

Names must match:

[A-Za-z_][A-Za-z0-9_]*

Sending non-empty env while resuming a chat returns 422.

Stdio MCP servers

Define a local MCP process with command, optional args, and optional env:

{
  "mcp_servers": [
    {
      "name": "linear",
      "command": "npx",
      "args": ["-y", "@tacticlaunch/mcp-linear"],
      "env": {
        "LINEAR_API_TOKEN": "lin_..."
      }
    }
  ]
}

Remote MCP servers

Define a remote server with url, optional transport type, and optional headers:

{
  "mcp_servers": [
    {
      "name": "figma",
      "url": "https://mcp.figma.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ..."
      }
    }
  ]
}

Remote type may be http or sse. Omitting it defaults to HTTP behavior in the runner.

MCP rules

Every server needs a unique name.
Each server must set exactly one of command or url.
bruin and agent-runner are reserved names.
Stdio arguments and environment values must be strings.
Remote header values must be strings.

MCP configuration is stored on the chat and inherited by every later turn. Unlike top-level env, MCP env and headers are therefore durable chat configuration. Do not resend mcp_servers with chat_id; the API returns 422.