MCP server

Expose Scorch search, scraping, mapping, and crawl operations to MCP-compatible AI clients through a lightweight stdio adapter.

Connection model

AI clientMCP host

→

scorch mcpstdio adapter

→

scorchdHTTP runtime

scorch mcp does not fetch pages, start a browser, or construct an engine. It translates Model Context Protocol tool calls into HTTP requests against SCORCH_API_URL. Server-side search, browser, concurrency, and network policy still apply.

The adapter uses the official Rust MCP SDK for JSON-RPC framing, generated input schemas, tool discovery, cancellation tokens, and the stdio lifecycle.

Start the service

scorchd

Confirm that the API is ready before starting an MCP host:

curl -fsS http://127.0.0.1:33000/ready | jq

The MCP adapter is not a service supervisor. Your process manager, shell, or container runtime should keep scorchd running separately.

Configure an MCP client

Add a stdio server entry to your MCP client's configuration. Use an absolute executable path because GUI applications often have a minimal PATH.

{
  "mcpServers": {
    "scorch": {
      "command": "/absolute/path/to/scorch",
      "args": ["mcp"],
      "env": {
        "SCORCH_API_URL": "http://127.0.0.1:33000"
      }
    }
  }
}

Restart or reload the MCP client after changing its configuration. The server should appear as scorch with six tools.

Connect to a gateway

{
  "mcpServers": {
    "scorch": {
      "command": "/home/user/.local/bin/scorch",
      "args": ["mcp"],
      "env": {
        "SCORCH_API_URL": "https://scorch.internal.example"
      }
    }
  }
}

Credentials belong at the gateway. The current client has no Scorch-specific token setting. For remote access, use gateway controls appropriate to your MCP host and deployment.

Available tools

Tool	Purpose	Important inputs
`scorch_search`	Search the public web and optionally scrape each result.	`query`, `limit`, `country`, `language`, optional `scrapeOptions`.
`scorch_scrape`	Fetch or render one public page and extract clean content.	`url` and optional `options`.
`scorch_map`	Discover normalized public URLs belonging to a site.	`url`, `limit`, subdomain and path filters.
`scorch_crawl_start`	Start a bounded in-memory crawl job.	`url`, `limit`, `maxDepth`, `concurrency`, filters, scrape options.
`scorch_crawl_status`	Read one page of job state, documents, and errors.	`id`, `cursor`, `pageSize`.
`scorch_crawl_cancel`	Cancel active work and remove a job.	`id`.

Tool schemas use the same contracts as the HTTP API. Unknown fields and out-of-range values are rejected by the service.

Example prompts

“Use Scorch to search for the latest Rust async runtime documentation and return five source URLs.”
“Scrape this page as Markdown and links. Render JavaScript only if Scorch determines it is needed.”
“Map up to 200 URLs on this documentation site, excluding /blog/.”
“Start a 30-page crawl at depth two, then poll it until complete and summarize the successful documents.”
“Capture a full-page screenshot with Obscura.”

The AI client decides how to call and compose tools. Scorch enforces the actual URL, browser, search-engine, capacity, and timeout rules.

Cancellation and process behavior

When an MCP host cancels a tool call, the adapter drops the corresponding HTTP request future. This stops waiting in the adapter. Crawl jobs have an explicit cancel tool because a successfully created job continues independently inside scorchd.

MCP JSON-RPC protocol traffic is written only to stdout. Diagnostics and startup failures are written to stderr. Do not wrap the command in a script that prints banners or log lines to stdout.

Endpoint selection order is:

--api-url passed before mcp
SCORCH_API_URL in the MCP server environment
http://127.0.0.1:33000

/absolute/path/to/scorch \
  --api-url http://127.0.0.1:33000 \
  mcp

Troubleshooting

The MCP server exits immediately

Run the configured command from a terminal and inspect stderr. Confirm that the binary path is absolute, executable, and built for the host architecture.

Tools fail with connection errors

Check the API separately:

SCORCH_API_URL=http://127.0.0.1:33000 scorch search "health check"
curl -v http://127.0.0.1:33000/ready

If the MCP host is sandboxed or containerized, 127.0.0.1 refers to that sandbox or container, not necessarily the machine running scorchd.

The client reports invalid JSON-RPC

Ensure no wrapper, shell startup file, or process supervisor writes informational text to stdout. Scorch itself keeps diagnostics on stderr.

A browser choice is rejected

The MCP schema may allow both backend names, but the service allowlist is authoritative. Inspect /ready and update SCORCH_ALLOWED_BROWSERS only if the deployment intends to permit that backend.