Agent Bridge

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. 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.

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

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

cd packages/mcp-server
pnpm build

Step 2: Install the Native Messaging Host

cd packages/mcp-server
./install.sh <your-extension-id>

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

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.

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

Claude Code
Cursor
Claude Desktop

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Add to your Claude Desktop config:

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

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 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)

All successful conversions are automatically saved to your Dashboard History, with AI-generated summaries and tags.

Usage Examples

Convert a Reddit thread

You: Convert this Reddit thread to Markdown: 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…

Batch convert for research

You: Batch convert these 5 Reddit URLs and summarize the key takeaways:

Agent: (calls agent_batch_convert) Converted 5/5 URLs successfully. Here are the key takeaways…

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.

AI chat exports (2)

Claude conversations · Other AI chat platforms (ChatGPT, Gemini, etc. via a shared DOM extractor)

Docs & knowledge bases (6)

Wikipedia · arXiv · OpenAI Docs · Mintlify-based docs sites · Notion · Google Docs

Dev & code (3)

GitHub Issues/PRs · Stack Overflow · dev.to

Publishing (3)

Medium · Substack · Product Hunt

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.

Video & media (1)

YouTube (transcript extraction)

Work & productivity (5)

Gmail · LinkedIn · Amazon (product pages) · Canvas LMS · XenForo forums

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

'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.

'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/

'Agent connection error' from MCP

The Native Host TCP server isn’t running. Make sure:

Chrome is open
The Web2MD extension is loaded
Service Worker console shows “TCP relay ready on port 12315”

'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.

'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).

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.

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.

Getting Started

Core Features

Advanced

Plans

Overview

Architecture

Setup

Step 1: Build the MCP Server

Step 2: Install the Native Messaging Host

Step 3: Configure MCP

Step 4: Verify

Available Tools

agent_convert

agent_batch_convert

bridge_convert_url

Usage Examples

Supported Sites

Troubleshooting

How It Differs from the MCP Server

​Overview

​Architecture

​Setup

​Step 1: Build the MCP Server

​Step 2: Install the Native Messaging Host

​Step 3: Configure MCP

​Step 4: Verify

​Available Tools

​agent_convert

​agent_batch_convert

​bridge_convert_url

​Usage Examples

​Supported Sites

​Troubleshooting

​How It Differs from the MCP Server

Overview

Architecture

Setup

Step 1: Build the MCP Server

Step 2: Install the Native Messaging Host

Step 3: Configure MCP

Step 4: Verify

Available Tools

agent_convert

agent_batch_convert

bridge_convert_url

Usage Examples

Supported Sites

Troubleshooting

How It Differs from the MCP Server