Configuration

scout.config.json

Every aspect of the Scout MCP server is tunable through a single JSON file. Drop a scout.config.json in your project root and Scout picks it up at startup — no environment variables, no CLI flags, no restarts.

How it works

Scout looks for a configuration file on startup in the following order:

1. SCOUT_CONFIG environment variable

If set, Scout reads the file at this path. Useful for CI or non-standard project layouts.

2. scout.config.json in the working directory

The default. Place the file next to your package.json and it's picked up automatically.

3. Built-in defaults

If no file is found, every property falls back to a sensible default. Scout works out of the box with zero configuration.

Quick start

Create a scout.config.json in your project root. You only need to include the properties you want to override — everything else uses its default value.

scout.config.jsonjson

{
  "server": {
    "port": 3000
  },
  "agent": {
    "maxSteps": 50
  }
}

Property reference

Select a section to explore its properties. Every property is optional — omit it to use the default value.

Server

server

Controls the HTTP and WebSocket server that the Scout MCP server exposes. Agents and extensions connect through this endpoint.

port

numberdefault: 9876

The port the Scout server listens on for HTTP and WebSocket connections. Must be between 1 and 65 535.

Complete example

A complete scout.config.json with every property set to its default value. Copy this as a starting point and remove what you don't need.

Click to expand

Tips

Practical advice for configuring Scout in different environments.

Start minimal

Only override what you need. Every property has a production-ready default. A minimal config is easier to maintain and less likely to conflict with future Scout updates.

Use environment-specific files

Set the SCOUT_CONFIG environment variable to point to different config files for development, staging, and production. This keeps your project root clean and avoids accidental config leaks.

Tune session limits for your workload

If your agents browse complex SPAs with heavy network traffic, increase maxRecentRequests and maxConsoleLogsPerType. For simple page scraping, the defaults are generous.

Agent safety nets

The agent section protects against runaway automation. If your tasks require long multi-step sequences, increase maxSteps. If you run many concurrent agents, raise maxRunners but monitor memory usage.

Perception tuning

Lower the heartbeat intervalMs for faster visual change detection at the cost of CPU. Raise the noiseThreshold if minor CSS animations are triggering false positives.