# VS Code MCP Setup

Cortex Scout is a **pure binary** MCP server (`cortex-scout-mcp`, stdio transport).

> **`RUST_LOG` warning:** Always use `RUST_LOG=warn`. At `info` or `debug` level the
> server emits hundreds of log lines per request to stderr; VS Code treats this as errors
> or times out waiting for valid JSON-RPC responses.

---

## 1. Get the binary

- Download `cortex-scout-mcp` (Linux/macOS) or `cortex-scout-mcp.exe` (Windows) from
  [GitHub Releases](https://github.com/cortex-works/cortex-scout/releases).
- Or build locally:

```bash
cd mcp-server

# Basic build
cargo build --release --bin cortex-scout-mcp

# Full build (adds hitl_web_fetch / visible-browser HITL)
cargo build --release --all-features --bin cortex-scout-mcp
```

---

## 2. Configure VS Code

The timeout guard env vars shown in the examples below are required. They are what force Cortex Scout to cancel a pathological fetch or stalled browser path instead of leaving the MCP client stuck forever.

VS Code reads MCP servers from two places:

| File | Top-level key | Scope |
|------|--------------|-------|
| `~/Library/Application Support/Code/User/mcp.json` (macOS global) | `"servers"` | All workspaces |
| `%APPDATA%\Code\User\mcp.json` (Windows global) | `"servers"` | All workspaces |
| `.vscode/mcp.json` in workspace | `"servers"` | This workspace only |
| `settings.json` in workspace | `"mcp.servers"` | This workspace only |

> **Key names:** The global `mcp.json` and the workspace `.vscode/mcp.json` both use the
> top-level key `"servers"`. The workspace `settings.json` uses `"mcp.servers"`. Claude
> Desktop, Cursor, and Windsurf use `"mcpServers"`.

### macOS / Linux

```jsonc
// ~/Library/Application Support/Code/User/mcp.json  (or .vscode/mcp.json)
{
  "servers": {
    "cortex-scout": {
      "type": "stdio",
      "command": "env",
      "args": [
        "RUST_LOG=warn",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS=90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SEARCH_STRUCTURED=120",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=45",
        "CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS=12",
        "CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS=4",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS=20",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_RETRY_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_FORCED_CDP_ATTEMPT=25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_NATIVE_CDP_FALLBACK=25",
        "SEARCH_ENGINES=google,bing,duckduckgo,brave",
        "LANCEDB_URI=/absolute/path/to/cortex-scout/lancedb",
        "HTTP_TIMEOUT_SECS=30",
        "MAX_CONTENT_CHARS=10000",
        "/absolute/path/to/cortex-scout/mcp-server/target/release/cortex-scout-mcp"
      ]
    }
  }
}
```

Default behavior is direct/no-proxy. Add `IP_LIST_PATH` and `PROXY_SOURCE_PATH` only if you want proxy support available. For an opt-in proxy setup, keep `ip.txt` empty and let `proxy_control grab` populate it only when an agent decides a retry should use proxies.

### Windows

Windows has no `env` command. Pass env vars as an object instead:

```jsonc
// %APPDATA%\Code\User\mcp.json
{
  "servers": {
    "cortex-scout": {
      "type": "stdio",
      "command": "C:\\Users\\YOU\\cortex-scout\\mcp-server\\target\\release\\cortex-scout-mcp.exe",
      "args": [],
      "env": {
        "RUST_LOG": "warn",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS": "90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL": "90",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SEARCH_STRUCTURED": "120",
        "CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT": "45",
        "CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS": "12",
        "CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS": "4",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS": "20",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT": "25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_RETRY_ATTEMPT": "25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_FORCED_CDP_ATTEMPT": "25",
        "CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_NATIVE_CDP_FALLBACK": "25",
        "SEARCH_ENGINES": "google,bing,duckduckgo,brave",
        "LANCEDB_URI": "C:\\Users\\YOU\\cortex-scout\\lancedb",
        "HTTP_TIMEOUT_SECS": "30",
        "MAX_CONTENT_CHARS": "10000"
      }
    }
  }
}
```

After editing any MCP config, **restart VS Code** (Cmd+Q / Alt+F4) to reload the tool list.

---

## 3. Tool catalog

| Tool | Purpose |
|------|---------|
| `web_search` | Multi-engine search. Use `include_content=true` for search+scrape in one call |
| `web_fetch` | Unified fetch family. Use `mode="single"|"batch"|"crawl"` |
| `deep_research` | Multi-step research: search + fetch + optional LLM synthesis |
| `extract_fields` | Primary structured field extraction from a URL |
| `memory_search` | Semantic recall from past research sessions (LanceDB) |
| `proxy_control` | Rotate / list / test outbound proxies |
| `visual_scout` | Headless screenshot (confirm auth gates) |
| `hitl_web_fetch` | Unified visible-browser HITL. Use `auth_mode="challenge"|"auth"` |
| `browser_automate` / `scout_browser_automate` | Stateful browser omni-tool for navigation, locators, tabs, screenshots/PDF, file upload, mocks, diagnostics, and browser-state setup |
| `browser_close` / `scout_browser_close` | Close the persistent automation session |
| `agent_profile_auth` / `scout_agent_profile_auth` | Visible login bootstrap for first-time auth, OAuth, 2FA, or CAPTCHA |

Legacy names (`web_search_json`, `web_fetch_batch`, `web_crawl`, `fetch_then_extract`, `human_auth_session`) remain callable as compatibility aliases.

> `hitl_web_fetch` requires the binary built with `--all-features`.

### Browser automation notes

- Prefer one `scout_browser_automate` call with a `steps` array instead of splitting a workflow across many tool turns.
- The automation surface now includes Playwright-style families: `tabs`, locator actions (`click_locator`, `assert_locator`), `wait_for`, `handle_dialog`, `file_upload`, `fill_form`, `mock_api`/`route_list`/`unroute`, `console_dump`, `network_dump`, `storage_state_*`, `cookie_*`, `localstorage_*`, `sessionstorage_*`, and `pdf_save`.
- If a domain needs an initial visible login, use `scout_agent_profile_auth` once, then return to headless automation.

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| No tools appear | Confirm binary path is correct and executable (`chmod +x`) |
| Tools time out | Set `RUST_LOG=warn` (not `info` or `debug`) |
| A fetch appears stuck for too long | Confirm your MCP config includes the required `CORTEX_SCOUT_TOOL_TIMEOUT_SECS*`, `CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS*`, `CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS`, and `CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS` guards, then fully restart VS Code |
| `hitl_web_fetch` missing | Rebuild with `--all-features` |
| Config not picked up | Fully restart VS Code after editing mcp.json |
| Proxy tools fail | Proxy support is optional. If you want it, set `IP_LIST_PATH`/`PROXY_SOURCE_PATH`; keep `ip.txt` empty by default and populate it only when needed |
