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 to http://127.0.0.1:33000 by default. 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"]
    }
  }
}

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": ["--api-url", "https://scorch.internal.example", "mcp"]
    }
  }
}

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 live-validated web, package, developer, security, and research sources and optionally scrape each result.	`query`, `limit`, `country`, `language`, optional `engines`, `categories`, and `scrapeOptions`.
`scorch_scrape`	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. Omitted engine selection uses only DuckDuckGo. Callers can explicitly choose from the server's 19 credential-free engines, including yahoo, crates-io, npm, docker-hub, pubmed, and the other documented sources. Unknown fields, removed engine names, 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.”
“Render a JavaScript-heavy page with Obscura and return its text.”

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.

The adapter connects to http://127.0.0.1:33000 unless --api-url is passed before mcp.

/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 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 render or browser field is rejected

Rendering and browser selection are no longer part of the scrape contract. Remove the field; every scrape uses embedded Obscura with stealth statically enabled.