# Connect OctoCrawl MCP

Choose your MCP client below. OctoCrawl currently connects through a [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) endpoint on the same computer as your client; hosted browser login is paused on the roadmap.

## Set up OctoCrawl MCP

Connect to the local OctoCrawl service on this computer.

### Codex

The macOS first-use setup normally adds this entry automatically. Use this command if it did not. (Run in terminal; Verified locally.)

```bash
codex mcp add w2l-local --url http://127.0.0.1:8791/mcp
```

Run codex mcp list, open a new Codex task, then use /mcp to check that preview_monitor is available.

Setup docs: https://developers.openai.com/codex/extend/mcp

### Claude Code

Add the local HTTP server to Claude Code in the current project. Run this in the checkout where you use Claude Code. (Run in terminal; Client task check pending.)

```bash
claude mcp add --transport http --scope local w2l-local http://127.0.0.1:8791/mcp
```

Run claude mcp list. In Claude Code, use /mcp to check the connection and tools before sending the first task.

Setup docs: https://code.claude.com/docs/en/mcp

### Cursor

Merge this server into your project .cursor/mcp.json (or your user-level ~/.cursor/mcp.json). Keep existing servers. (Copy config; Client task check pending.)

```json
{
  "mcpServers": {
    "w2l-local": {
      "url": "http://127.0.0.1:8791/mcp"
    }
  }
}
```

Reload Cursor, then check MCP tools in its settings. In Cursor CLI, cursor-agent mcp list-tools w2l-local lists tools.

Setup docs: https://prod.cursor.com/help/customization/mcp

### OpenCode

For OpenCode 1.x, merge this entry into the mcp object in opencode.json. Keep your existing settings and servers. (Copy config; Client task check pending.)

```json
{
  "mcp": {
    "w2l-local": {
      "type": "remote",
      "url": "http://127.0.0.1:8791/mcp",
      "enabled": true
    }
  }
}
```

Run opencode mcp list and confirm w2l-local is connected, then ask for the sample task below.

Setup docs: https://opencode.ai/docs/mcp-servers

Using another MCP client? Point it at `http://127.0.0.1:8791/mcp`. Hosted HTTPS and browser login are paused on the roadmap; see Hosted connection below.


## Start OctoCrawl on your computer

On macOS, from an OctoCrawl repository checkout, use Node.js 22.13+ or 24+:

```bash
npm ci
npm run first-use:local
npm run local:mcp:status
```

The setup prepares Chromium and starts the managed local service. It also attempts to register OctoCrawl with **Codex**. Keep the service running while you use MCP. The local endpoint is `http://127.0.0.1:8791/mcp`; it is only reachable from this computer and does not require browser login. On another system, build the repository and run `npm run local:mcp` in a terminal; the managed macOS receiver setup is unavailable there.

Registration alone does not prove a task works. After adding the server, check that `w2l-local` is connected, that `preview_monitor` appears, and then send the sample task below. If the server is missing, check `npm run local:mcp:status` and restart or reload the client. The Codex path has been verified locally; the other client snippets follow their documented configuration formats and still need an OctoCrawl task-level check.

## Send your first task

```text
Use OctoCrawl's preview_monitor with preset firecrawl-introduction. Show the sample quality, source URL, field evidence, and any missing reasons. Do not create a persistent Monitor yet.
```

Expected output is a **nonpersistent** sample assessment. It does not create a baseline, scheduled run, or webhook delivery. If the connection is absent, check `npm run local:mcp:status`, the saved entry with `codex mcp list`, and then open a new Codex task. If the sample is blocked or incomplete, inspect the reported reason before creating a Monitor.

Then continue with [Monitor → HTTPS Webhook](/docs/guides/monitor-webhook/) or [Amazon.sg product JSON](/docs/guides/amazon-product/).

## Hosted connection

**Paused.** There is no permanent HTTPS MCP URL, hosted login, or copyable remote command. The [roadmap](https://github.com/77777R7/w2l/blob/main/ROADMAP.md#paused) puts a hosted API and hosted MCP on hold until people need runs while their computer is off; until then, OctoCrawl MCP runs on your own computer as described above.