Toolsets

Tool Server Protocol

Tool servers expose a standard HTTP API. Any service that implements this protocol can be used as a tool in the Simulation Lab. See the Tool Server Protocol reference for the full spec.

Multi-Tool Composition

A workspace can include multiple tool servers. The agent sees a unified tool list. Tools are automatically namespaced by their server name (e.g., email-env__send_email, chronos-server__create_event). Routing is handled transparently; the agent calls tools by name and the Simulation Lab forwards each call to the correct server.

Tool Definition Format

Each tool server is defined as a YAML file that maps directly to Docker Compose services. Here is the email tool as an example:

name: email
display_name: Email
description: Email sending and inbox management via SMTP server.
category: communication

exposed_ports:
  - port: 8025
    description: Email web UI

services:
  smtp-server:
    image: <smtp-image>
    ports: ["8025", "1025"]
    healthcheck:
      interval: 10s
      retries: 6

  email-env:
    image: <tool-server-image>
    environment:
      SMTP_BASE_URL: http://smtp-server:8025
    depends_on:
      smtp-server:
        condition: service_healthy

The YAML specifies everything Docker needs: images, ports, health checks, environment variables, and dependency ordering. The CLI reads these definitions and composes them into a working docker-compose.yml. For tools that are hosted externally and don’t need Docker services, use the tool_server_url field instead:

name: harbor-main
display_name: Harbor Main
description: Custom tool scaffold for harbor-main.
category: custom
tool_server_url: http://localhost:9000

Built-in Toolsets

Below is a selection of out-of-the-box tools that come with Simulation Lab. We are continually adding more domain-specific tools as part of our roadmap.

Name	Category	Description
`Calendar`	Productivity	CalDAV calendar (Baikal + Chronos MCP)
`Coding`	Development	Sandboxed shell and filesystem (OpenHands)
`Email`	Communication	Email sending/inbox via MailHog SMTP
`File Explorer`	Development	Read, write, and list files
`Frappe HRMS`	Enterprise	Full HR management system (Frappe HRMS)
`Google Workspace`	Productivity	Drive, Docs, Sheets, Gmail, Calendar
`Nano Bananna Pro`	Creative	Image generation and editing
`OpenTable`	Lifestyle	Restaurant search, reservations, and cancellations
`Outlook`	Communication	Email inbox, drafts, and sent items
`Playwright`	Browser	Browser automation via Playwright MCP
`Rocket.Chat`	Communication	Open source Slack-equivalent Team chat
`SEC Edgar`	Finance	SEC EDGAR filings search
`Terminal`	Development	Run shell commands
`Twelve Data`	Finance	Market data
`Weather`	Utilities	Forecasts by location
`WhatsApp`	Communication	Messaging with contacts, groups, and messages

Bring Your Own Tools

Simulation Lab supports three paths for integrating custom tools: MCP servers, env-local custom tool definitions, and custom CLI tools for coding environments.

Custom MCP Servers

You can add custom MCP servers to any environment so the agent can call them alongside built-in tools. SimLab supports two MCP transport patterns:

URL-based — SimLab connects directly to an HTTP MCP endpoint. No extra container is added.
Command-based — SimLab adds an mcp-gateway container that starts your stdio MCP servers and exposes them over HTTP inside the environment.

Configuration format

Create a mcp-servers.json file with a top-level mcpServers object. Each server must define exactly one of url or command:

{
  "mcpServers": {
    "docs": {
      "url": "https://example.com/mcp"
    },
    "weather": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/adhikasp/mcp-weather.git", "mcp-weather"],
      "env": {
        "ACCUWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Field	Required	Description
`url`	One of `url` or `command`	HTTP endpoint for URL-based servers
`command`	One of `url` or `command`	Executable for command-based (stdio) servers
`args`	No	Arguments passed to the command
`env`	No	Environment variables (e.g. API keys) for command-based servers

Naming rules:

Server names may contain only letters, numbers, _, and -.
Names must not collide with built-in tool server names (e.g. email, calendar).

Adding MCP servers to an environment

Pass your config at env init:

# URL-based only
simlab env init my-env --mcp-servers ./mcp-servers.json --non-interactive

# Combined with a template
simlab env init my-env --template hr --mcp-servers ./mcp-servers.json

# Command-based (adds an mcp-gateway container automatically)
simlab env init my-env --mcp-servers ./mcp-servers-command.json --non-interactive

After init, SimLab persists the config as environments/<env-name>/mcp-servers.json. For command-based servers, it also generates an mcp-gateway service in docker-compose.yml.

Managing API keys and env vars

For command-based servers, set secrets in environments/<env-name>/.env before running simlab env up. If an env var name is used by only one MCP server, set it directly:

# environments/my-env/.env
ACCUWEATHER_API_KEY=your-real-key

If multiple servers share the same env var name, use the scoped form:

# environments/my-env/.env
SIMLAB_MCP_WEATHER__API_KEY=weather-key
SIMLAB_MCP_DOCS__API_KEY=docs-key

Server names are normalized for scoped env vars by uppercasing and replacing non-alphanumeric characters with _ (e.g. my-docs becomes MY_DOCS).

Env-Local Custom Tool Definitions

For environment-specific tool servers that aren’t part of the built-in catalog, you can scaffold custom tool definitions under the environment’s custom-tools/ directory. These use the same YAML schema as built-in catalog tools.

Scaffold a custom tool

simlab env custom-tools add my-env harbor-main

This creates the following layout:

environments/my-env/
  env.yaml
  docker-compose.yml
  .env
  custom-tools/
    harbor-main.yaml

The command also adds harbor-main to the tools list in env.yaml and regenerates the environment’s Docker Compose and related files.

Edit and regenerate

After editing custom-tools/*.yaml, env.yaml, or mcp-servers.json, regenerate the environment:

simlab env init my-env --force

SimLab will also detect stale generated files when you run simlab env up, simlab tasks run, or simlab tasks seed, and prompt to regenerate in interactive sessions.

Inspect a custom tool

simlab tools info harbor-main --env my-env

Naming rules

Custom tool names must not shadow built-in tool names.
Env-local custom tool names must be unique within the environment.
MCP server names must not conflict with either built-in or env-local tool names.

Custom CLI Tools (Coding Environments)

For coding environments that need extra CLI tooling installed in the sandbox, you can customize the environment with setup scripts, mounted fixtures, and reusable skills.

Layout

environments/my-env/
  env.yaml
  coding/
    setup/
      install-tools.sh      # Installs extra CLIs (e.g. pdftotext, xlsx2csv)
    fixtures/
      report.pdf             # Files mounted into /workspace/fixtures
      data.xlsx
    skills/
      pdf-xlsx-reporting/
        SKILL.md             # Reusable instructions for the coding agent

Setup script

The setup script runs inside the coding sandbox at startup. Use it to install any tools your tasks require:

#!/usr/bin/env bash
set -euo pipefail
apt-get update -qq && apt-get install -y -qq poppler-utils
uv pip install --quiet --system xlsx2csv

Running with custom CLI tools

simlab env init my-env --force
simlab tasks run --env my-env \
  --tasks-dir ./task-bundle \
  --task workspace_asset_report \
  --agent-model <model> \
  --agent-api-key "$SIMLAB_AGENT_API_KEY"

Task Generation with Custom Tools

Custom tools (both MCP and env-local) are available for task generation. Provide your tool definitions and the pipeline produces tasks, seed data, and verifiers tailored to your tools:

simlab tasks-gen run --config ./taskgen/config.toml

At runtime, the agent discovers custom tools through the same unified tool list as built-in tools and calls them transparently.

Introduction

Simulation Lab

Core Concepts

Tool Server Protocol

Multi-Tool Composition

Tool Definition Format

Built-in Toolsets

Bring Your Own Tools

Custom MCP Servers

Configuration format

Adding MCP servers to an environment

Managing API keys and env vars

Env-Local Custom Tool Definitions

Scaffold a custom tool

Edit and regenerate

Inspect a custom tool

Naming rules

Custom CLI Tools (Coding Environments)

Layout

Setup script

Running with custom CLI tools

Task Generation with Custom Tools

​Tool Server Protocol

​Multi-Tool Composition

​Tool Definition Format

​Built-in Toolsets

​Bring Your Own Tools

​Custom MCP Servers

​Configuration format

​Adding MCP servers to an environment

​Managing API keys and env vars

​Env-Local Custom Tool Definitions

​Scaffold a custom tool

​Edit and regenerate

​Inspect a custom tool

​Naming rules

​Custom CLI Tools (Coding Environments)

​Layout

​Setup script

​Running with custom CLI tools

​Task Generation with Custom Tools

Tool Server Protocol

Multi-Tool Composition

Tool Definition Format

Built-in Toolsets

Bring Your Own Tools

Custom MCP Servers

Configuration format

Adding MCP servers to an environment

Managing API keys and env vars

Env-Local Custom Tool Definitions

Scaffold a custom tool

Edit and regenerate

Inspect a custom tool

Naming rules

Custom CLI Tools (Coding Environments)

Layout

Setup script

Running with custom CLI tools

Task Generation with Custom Tools