Scout setup options

Workspace and worktrees

The installation guide pins your repository with --root. Scout starts its index without a separate load call.

For a portable configuration, omit --root and start the client inside the intended Git checkout. Scout detects the enclosing checkout.

Ignore rules exclude nested worktrees under ignored paths. Check the active root and search coverage before accepting an empty result.

Use load to change an existing server root. Outside roots require acknowledge: true. The development build lets the agent add repositories without replacing the current selection.

Project scope determines which client loads a configuration. The path arguments determine which files the server can access.

The default absolute paths select one fixed checkout. Update those paths in each worktree; avoid committing machine-specific paths.

For portable relative paths, set the server launch directory to the worktree root. Relative paths resolve from that directory, not the configuration file.

Git does not copy ignored configuration files into new worktrees. Copy local files when needed. The development build can serve several worktrees in one process.

Compare git rev-parse --show-toplevel with server_status before you query or change code. Correct a mismatched path and reconnect.

Several agents and server resources

Scout supports stdio only. Assign repository searches to one agent if your workflow otherwise starts a separate Scout server for each agent.

Share search results with the other agents. A separate stdio client can start another server with its own index and watchers.

Configure the server only for its owner when the client supports separate agent configurations. Other agents must omit its automatic startup entry.

If your client always starts every configured server for every agent, task assignment alone cannot reduce the process count.

Share a server only between agents with the same workspace and permissions. Use separate instances for different worktrees. Give HTTP instances separate ports.

HTTP transport does not guarantee safe concurrent edits. Coordinate changes that affect another agent’s results.

Choose one connection configuration per product. Remove duplicate manual and plugin entries, including stdio entries alongside an HTTP connection.

Duplicate servers consume memory and file descriptors. If your client reports too many open files, check its server registrations and active instances.

Agent instructions

Add this instruction to your project instructions after the connection works. Use CLAUDE.md for Claude Code or AGENTS.md for Codex.

For another client, use its documented project instruction file.

Install the product skill described in the skills and plugins section below. It guides workspace checks, tool selection, and result interpretation.

Use the scout mcp find tool as the primary workspace search instead of shell grep, rg, or find. Strict modes (literal, regex, word) are exhaustive; fuzzy is ranked. If glider (C#) or tglider (TypeScript/JavaScript) is installed, prefer it for its language; use scout for every other language and as the universal fallback. Text search is the exception: tglider has no text-search tool, so literal and regex hunts in TypeScript and JavaScript belong to scout even when tglider is installed, and glider searches only the documents its workspace loaded.

Optional semantic search

Scout uses lexical search by default. Semantic search adds matches by meaning and requires more memory, disk space, and initial compute.

Add --semantic to enable it for every startup root. The first start downloads an embedding model of about 86 MiB.

For mixed settings, omit --semantic and set semantic.enabled in each root configuration. Runtime load overrides take precedence over startup flags and configuration.

Scout checks the model checksum and stores it in ~/.glidermcp/models/. Repositories share that model, but each repository needs its own embeddings.

Initial work grows with repository size. Lexical search remains available while embeddings are prepared; server_status reports progress.

To disable the tier, remove --semantic and any enabled root configuration or runtime override. Scout supports stdio only.

The development build reloads named configurations through load. sync retains configuration snapshots. Unidentified old semantic indexes rebuild once; cached models remain reusable.

Updates and expired packages

The recommended npx connection checks the latest tag at each server start. Restart to select a newer version; active processes keep their version.

npx caches downloaded packages but can require registry access at startup. Use an exact package version for a fixed release.

For offline use, install a fixed version globally while online. Launch that executable directly and retain only its server arguments.

For native or global installations, use the same installation method for manual updates. Restart the server afterward.

To migrate, replace the existing entry with the installation guide configuration. Keep your server flags and avoid duplicate registrations.

On Windows, the generated cmd.exe command launches npx. For a native alternative, use the installed executable with its server arguments.

Future packages will expire 90 days after release. Existing versions retain their embedded expiry. Fixed and offline versions still expire.

Optional global npm installation

Set the client command to scout and remove -y and @glidermcp/scout@latest. Keep the server arguments. Native installations use the same executable configuration.

npm install --global @glidermcp/scout@latest
scout --version

Homebrew

Update the tap, then upgrade Scout. Unpin the formula first if you pinned its version.

brew update
brew upgrade glidermcp/tap/scout
scout --version

Standalone installer

Run the installer again. It replaces the binary in ~/.local/bin. Keep the same SCOUT_INSTALL_DIR if you chose another directory. Clear SCOUT_VERSION if it pins an older release.

curl -fsSL https://glidermcp.com/install.sh | sh
scout --version

If the connection fails

Executable not found: run npx -y @glidermcp/scout@latest --version in your terminal. Restart the client after installation so it receives the updated PATH.

If a GUI client still cannot find the executable, use its full path. Windows npm packages use a .cmd shim through cmd.exe.

If a plugin uses npx, complete its package download with the same user and npm cache as the client. Reconnect afterward.

A cached npx package can still require a registry check. A tool timeout does not extend the initial connection timeout.

Connection refused or server missing: check the client configuration location, JSON or TOML syntax, project trust, and server logs.

Timeout: wait for initial workspace preparation. Increase the client startup or tool timeout only if its documentation supports that setting.

Wrong workspace or failed load: check server_status, correct the path in the connection entry, and restart the server.

If a server with this name already exists, edit its entry. Do not append another entry with the same name.

Product skills and plugins

Install the skill for each product you use. Claude Code and Codex plugins bundle the skill with a stdio connection. TGlider and Scout use npx and need Node.js/npm.

Already connected? Keep your manual entry and install only the skill. This preserves project preload and custom server arguments.

For a new plugin connection, remove or disable an existing manual entry for that product. Start a new client session afterward. Portable plugins use their default workspace behavior. Use the installation guide for explicit paths.

In Claude Code:

/plugin marketplace add glidermcp/glidermcp
/plugin install scout@glidermcp

In Codex, add the marketplace, then choose the product in the Plugin Directory or /plugins browser.

codex plugin marketplace add glidermcp/glidermcp

Other Scout installers

For macOS or Linux without Node.js, choose Homebrew or the standalone installer. Run only one installer.

brew install glidermcp/tap/scout

curl -fsSL https://glidermcp.com/install.sh | sh