Purpose
Feedthrough is a debugging bridge embedded inside a web application that exposes internal runtime information from the page to AI agents via MCP (Model Context Protocol). The problem it solves is this: traditional browser MCP tools are external observers that control the browser from the outside via Puppeteer or CDP, and only support Chrome; whereas Feedthrough runs inside the page, allowing it to observe and drive the page without disrupting the execution environment.
Main capabilities
Feedthrough exposes DOM state, console logs, network requests, and user interactions all as MCP tools. Any MCP-compatible AI agent can inspect and drive the page in real time in a conversational manner. Because it runs inside the page, it can access framework-internal information such as the React component tree, Redux store, and custom global variables. It supports any browser, not just Chrome; it can be integrated into existing development workflows without launching a separate controlled browser; and during test runs it can also use Cypress's own browser context.
The tools it exposes include: connection_status() to confirm whether the bridge is connected; get_console_logs() to retrieve errors and application output; get_network_requests() to view failed requests, erroneous URLs, or missing calls; query_dom(selector) to find elements and inspect rendered content; inspect_element(selector) to take a deeper look at a specific element; click() / fill() for interactive operations.
How to use
- Start the MCP server: the server listens for browser connections at ws://127.0.0.1:8765 and exposes MCP tools over stdio. The port can be overridden with FEEDTHROUGH_PORT=9000. If the port is already in use, the server will move on to the next free port instead of refusing to start.
- Add it to the MCP client configuration.
- Inject the bridge into the page: Vite + React / Vue / Solid / Preact are supported, and it can also be used manually with any bundler.
- Open the page and start asking questions. Once the bridge is connected, [feedthrough] tab connec will be displayed in the MCP server outputted. It is recommended to keep a single tab open to avoid ambiguity; multiple tabs can connect at the same time, and commands are routed to the most recently active tab.
Recommended workflow: connection_status() first confirms the bridge is connected; get_console_logs() checks errors and application output; get_network_requests() finds failed requests; query_dom(selector) finds elements; inspect_element(selector) drills into a specific element; after click() / fill() interactions, re-check logs and network.
Project memory snippets can be added to CLAUDE.md, .cursor/rules/*.md, and similar files.
For one-off sessions, an example system prompt can be used.
When to use
Feedthrough is suitable for debugging web applications in a local development environment, including finding issues that are not visible in the UI but can be discovered through logs, network requests, and DOM queries. The example examples/react-app is a small React app containing three intentionally introduced bugs, ideal for trying out the diagnostic workflow: connect an AI agent and have it find the problems; all three bugs can be discovered within a minute via get_console_logs, get_network_requests, and query_dom. It is also supported for use during Cypress/Playwright test runs.
Limitations and caveats
v1 is local-use only, guaranteed by two safeguards: the WebSocket server binds to 127.0.0.1 and cannot be accessed from other machines on the network; the Origin header is checked for every incoming WebSocket connection, loopback origins (localhost, 127.0.0.1, ::1) are always accepted, and any host ending with an allowed suffix is also accepted (default .test); the suffix list can be overridden with FEEDTHROUGH_ALLOWED_HOST_SUFFIXES, and other origins are rejected.
Captured network requests include request and response bodies and headers, including Authorization, Cookie, and other headers sent by the application. This data leaves the page via the local WebSocket, flows through the MCP server, and reaches the connected AI agent. If that agent is cloud-backed, sensitive values reach the provider. ThereforeFeedthrough should only be run on development machines and development data; do not inject @feedthrough/core into production builds.
Live edits set_style / set_attribute / set_text are only previews of the running DOM, are not written back to source code, and are reset after reload/HMR. Framework-owned changes may be overwritten on the next render, and tool results will flag this.
When running multiple sessions, each AI agent session starts its own Feedthrough MCP server, and only one can occupy port 8765. The server falls through to the next free port and reports its location. connection_status() reports the actual bound port. All build tool adapters (vite, webpack, nextjs, nuxt, sveltekit, remix) read FEEDTHROUGH_PORT (or FEEDTHROUGH_URL as a full ws:// URL) when the Node configuration loads, and bake it into the injected bridge. If you start the development server yourself, when the environment variable is not set the page falls back to 8765, which may be another session's server.
A port can be pinned per project by setting it separately in .mcp.json and the app configuration. Each server picks a readable name on startup (such as quiet-olive-heron) and sends it to every connected page; the page logs one line in the browser console, stores it on window.__feedthrough.server, and returns it from get_page_info(). The agent's own name comes from connection_status().
Requirements
Requires Node.js >= 22 and pnpm. Packages are versioned independently, lifting only the packages that actually change. Publishing to npm is handled by CI. MIT licensed.
