> ## Documentation Index
> Fetch the complete documentation index at: https://web2md.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Bridge

> Let AI agents batch-convert Reddit and any website via your Chrome extension

## Overview

Agent Bridge lets AI agents (Claude Code, Cursor, Cowork, etc.) remotely control the Web2MD Chrome extension to batch-convert URLs — especially Reddit, JS-rendered, and login-protected pages that block server-side API access.

Instead of calling the Web2MD API (which Reddit blocks), the AI agent sends commands to your local Chrome extension via [Native Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging). The extension opens each page in a background tab using **your real browser session** — with your cookies and login state — extracts the content, converts to Markdown, and returns the result.

<Note>
  Agent Bridge requires a **PRO plan** and the **native messaging host** installed on your machine. The extension must be open in Chrome.
</Note>

## Architecture

```
AI Agent ←MCP/stdio→ MCP Server ←TCP:12315→ Native Host ←NM→ Chrome Extension → Any Website
```

| Component | Role |
| - | - |
| **AI Agent** | Claude Code, Cursor, Cowork — calls MCP tools |
| **MCP Server** | Translates MCP tool calls to TCP messages |
| **Native Host** | Relays between TCP and Chrome Native Messaging |
| **Chrome Extension** | Opens tabs, extracts HTML, converts to Markdown |

All communication is **local** — nothing leaves your machine. The Native Host listens on `localhost:12315` only.

## Setup

### Step 1: Build the MCP Server

```bash theme={null}
cd packages/mcp-server
pnpm build
```

### Step 2: Install the Native Messaging Host

```bash theme={null}
cd packages/mcp-server
./install.sh <your-extension-id>
```

<Tip>
  Find your Extension ID at `chrome://extensions` with Developer Mode enabled. Look for Web2MD and copy the ID string (e.g. `ijmgpkkfgpijifldbjafjiapehppcbcn`).
</Tip>

<Warning>
  After installation, you must **fully quit Chrome (Cmd+Q on Mac) and reopen it**. Chrome only reads Native Messaging manifests at startup — reloading the extension is not enough.
</Warning>

The install script:

* Copies host files to `~/.web2md/` (avoids macOS TCC restrictions on `~/Desktop`)
* Resolves the absolute path to `node` (Chrome launches with minimal PATH)
* Writes the NM manifest to Chrome's `NativeMessagingHosts` directory

### Step 3: Configure MCP

<Tabs>
  <Tab title="Claude Code">
    Add to `~/.claude/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop config:

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Step 4: Verify

In Chrome, open `chrome://extensions` → click Web2MD's "Service Worker" link → check the Console:

```
[Web2MD] Service worker started
[Web2MD] Connected to native host
[Web2MD] Native host TCP relay ready on port 12315
```

If you see these three lines, Agent Bridge is working.

## Available Tools

Agent Bridge exposes three MCP tools — pick based on transport and batching needs. All three are documented in full on the [MCP Server](/docs/advanced/mcp-server) page; this is the quick comparison.

| Tool | Transport | Batching |
| - | - | - |
| `bridge_convert_url` | HTTP (extension fetches HTML, server converts it) | Single URL |
| `agent_convert` | Native messaging (this page's architecture) | Single URL, optional `skill` param |
| `agent_batch_convert` | Native messaging | Up to 50 URLs, sequential |

### agent\_convert

Convert a single URL using the Chrome extension over native messaging.

| Parameter | Type | Description |
| - | - | - |
| `url` | string | The URL to convert |
| `skill` | string (optional) | Skill id or name — its body is appended to the returned Markdown |

**Returns:** Markdown content with title, source URL, word count, and reading time.

**Best for:** Reddit threads, login-protected pages, JS-rendered sites.

### agent\_batch\_convert

Batch convert up to 50 URLs. URLs are processed sequentially — the extension opens each page in a background tab, extracts content, closes the tab, then moves to the next.

| Parameter | Type | Description |
| - | - | - |
| `urls` | string\[] | Array of URLs to convert (max 50) |

**Returns:** Per-URL results streamed as they complete, plus a summary.

**Best for:** Research workflows — batch-convert Reddit threads, HN discussions, or competitor pages for AI analysis.

### bridge\_convert\_url

Convert a single URL by fetching its HTML through the extension over a local HTTP bridge (instead of native messaging), then converting server-side. Functionally similar to `agent_convert` for one-off conversions, but doesn't require the native messaging host — only the extension needs to be installed and running.

| Parameter | Type | Description |
| - | - | - |
| `url` | string | The URL to convert |
| `extensionId` | string (optional) | Override extension ID (auto-discovered from your API key if omitted) |

<Info>
  All successful conversions are automatically saved to your [Dashboard History](https://web2md.org/dashboard/history), with AI-generated summaries and tags.
</Info>

## Usage Examples

<AccordionGroup>
  <Accordion title="Convert a Reddit thread">
    **You:** Convert this Reddit thread to Markdown: [https://www.reddit.com/r/LangChain/comments/1siwh6q/](https://www.reddit.com/r/LangChain/comments/1siwh6q/)...

    **Agent:** *(calls `agent_convert`)* Here's the converted thread with 7 comments discussing RAG precision for legal documents...
  </Accordion>

  <Accordion title="Batch convert for research">
    **You:** Batch convert these 5 Reddit URLs and summarize the key takeaways:

    * [https://reddit.com/r/MachineLearning/comments/](https://reddit.com/r/MachineLearning/comments/)...
    * [https://reddit.com/r/LocalLLaMA/comments/](https://reddit.com/r/LocalLLaMA/comments/)...
    * [https://reddit.com/r/LangChain/comments/](https://reddit.com/r/LangChain/comments/)...
    * [https://reddit.com/r/artificial/comments/](https://reddit.com/r/artificial/comments/)...
    * [https://reddit.com/r/ChatGPT/comments/](https://reddit.com/r/ChatGPT/comments/)...

    **Agent:** *(calls `agent_batch_convert`)* Converted 5/5 URLs successfully. Here are the key takeaways...
  </Accordion>

  <Accordion title="Convert login-protected pages">
    **You:** Convert my company's internal wiki page at [https://wiki.internal.com/architecture](https://wiki.internal.com/architecture)

    **Agent:** *(calls `agent_convert`)* Since you're logged in to this site in Chrome, I was able to extract the full content...
  </Accordion>
</AccordionGroup>

## Supported Sites

Agent Bridge uses the same 27 site-specific extractors as the extension — each one knows how to pull clean content out of a site's DOM or API instead of falling back to raw page HTML.

<AccordionGroup>
  <Accordion title="Social & discussion (7)">
    Reddit · Hacker News · Twitter/X · Quora · Xiaohongshu (小红书) · Zhihu (知乎) · Instagram
  </Accordion>

  <Accordion title="AI chat exports (2)">
    Claude conversations · Other AI chat platforms (ChatGPT, Gemini, etc. via a shared DOM extractor)
  </Accordion>

  <Accordion title="Docs & knowledge bases (6)">
    Wikipedia · arXiv · OpenAI Docs · Mintlify-based docs sites · Notion · Google Docs
  </Accordion>

  <Accordion title="Dev & code (3)">
    GitHub Issues/PRs · Stack Overflow · dev.to
  </Accordion>

  <Accordion title="Publishing (3)">
    Medium · Substack · Product Hunt
  </Accordion>

  <Accordion title="CJK platforms (4)">
    WeChat (微信公众号) · Bilibili (哔哩哔哩) · Feishu (飞书) — plus Xiaohongshu and Zhihu above. The code marks this whole category as its highest-differentiation extractor group — few competitors handle these platforms at all.
  </Accordion>

  <Accordion title="Video & media (1)">
    YouTube (transcript extraction)
  </Accordion>

  <Accordion title="Work & productivity (5)">
    Gmail · LinkedIn · Amazon (product pages) · Canvas LMS · XenForo forums
  </Accordion>
</AccordionGroup>

Any URL without a dedicated extractor falls back to full-page HTML extraction — it still works, just without the site-specific cleanup (removing nav chrome, ads, comment widgets, etc.) that the specialized extractors apply. Sites that expose a public API (Reddit, Hacker News, GitHub, Stack Overflow) are fetched via that API when possible — faster and more reliable than opening a background tab. Everything else opens the page in a background tab and extracts from the rendered DOM.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Native host not installed' or 'not found'">
    Chrome hasn't loaded the NM manifest. **Fully quit Chrome (Cmd+Q) and reopen.** Simply reloading the extension is not enough.
  </Accordion>

  <Accordion title="'Native host has exited' immediately">
    Chrome can't execute the host script. Common causes:

    * `node` not found — re-run `./install.sh` which uses the absolute node path
    * Host is in a TCC-protected directory (`~/Desktop`, `~/Documents`) — re-run install to move to `~/.web2md/`
  </Accordion>

  <Accordion title="'Agent connection error' from MCP">
    The Native Host TCP server isn't running. Make sure:

    1. Chrome is open
    2. The Web2MD extension is loaded
    3. Service Worker console shows "TCP relay ready on port 12315"
  </Accordion>

  <Accordion title="'Failed to extract content from the page'">
    The extension is not logged in. Open the Web2MD popup in Chrome and sign in to your PRO account.
  </Accordion>

  <Accordion title="'Tab load timeout'">
    The target page takes too long to load. This is normal for slow sites. The extension waits up to 15 seconds per tab. Reddit uses the JSON API extractor and doesn't need a tab, so timeouts on Reddit usually mean the post URL is invalid (404).
  </Accordion>

  <Accordion title="Conversions not appearing in Dashboard History">
    History saving requires the extension to be logged in with a PRO account. The save is fire-and-forget — if the API call fails silently, conversions won't appear. Check that your auth token is valid.
  </Accordion>
</AccordionGroup>

## How It Differs from the MCP Server

| Feature | `convert_url` | `bridge_convert_url` | `agent_convert` / `agent_batch_convert` |
| - | - | - | - |
| Where it runs | Server-side API call | Extension fetches HTML, server converts it | Your local Chrome browser (native messaging) |
| Reddit support | ❌ Blocked by Reddit | ✅ Uses real browser session | ✅ Uses real browser session |
| Login-protected pages | ❌ No access | ✅ Uses your cookies | ✅ Uses your cookies |
| JS-rendered pages | ❌ No JavaScript | ✅ Full Chrome rendering | ✅ Full Chrome rendering |
| Setup required | API key only | Extension installed + running | Extension + native messaging host installed |
| Batching | — | Single URL only | Up to 50 URLs (`agent_batch_convert`) |
| Requires Chrome open | No | Yes | Yes |

**Rule of thumb:** Use `convert_url` for public pages. Use `bridge_convert_url` when you want the extension's browser session but don't want to install the native messaging host. Use `agent_convert` / `agent_batch_convert` for Reddit, authenticated pages, JS-heavy sites, or when you need to batch — or want a Skill applied via `agent_convert`'s `skill` param.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.