> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collinear.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Toolsets

> Built-in tools, custom tool definitions, and MCP server integration

## 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](/api-reference/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:

```yaml theme={null}
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:

```yaml theme={null}
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`:

```json theme={null}
{
  "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`:

```bash theme={null}
# 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:

```bash theme={null}
# environments/my-env/.env
ACCUWEATHER_API_KEY=your-real-key
```

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

```bash theme={null}
# 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

```bash theme={null}
simlab env custom-tools add my-env harbor-main
```

This creates the following layout:

```text theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```text theme={null}
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:

```bash theme={null}
#!/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

```bash theme={null}
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:

```bash theme={null}
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.