Feedthrough

Feedthrough

Debug with AI — from inside your app.

Feedthrough injects a lightweight debug bridge into any running web page, then exposes everything — DOM state, console logs, network requests, and user interactions — as MCP tools. Any MCP-compatible AI agent can inspect and drive the page conversationally, in real time.

Browser (any)

└── @feedthrough/core ← injected into your page ├── console interceptor ├── fetch / XHR interceptor └── DOM inspector ↕ WebSocket @feedthrough/mcp ← MCP server, exposes tools over stdio └── Tools: click, fill, inspect_element, query_dom, get_console_logs, get_network_requests, … ↕ MCP protocol Claude Code / Cursor / any MCP client

---

The name

Many physics and chemistry experiments run inside a sealed vacuum chamber, with all the air pumped out so nothing contaminates the experiment. The catch: you still need to control instruments inside the chamber and read their measurements, and the smallest air leak ruins the run. A feedthrough is the part that solves this — a specially engineered connector that carries electrical signals through the chamber wall while keeping the vacuum perfectly intact. You can't reach inside, but the feedthrough lets you observe and control what's happening in there anyway.

The parallel is exact: Feedthrough extracts runtime debug data from inside a running web app without disturbing it, and sends control signals back in — clicks, keystrokes, DOM queries — without breaking the execution environment.

---

Why Feedthrough?

Every other browser MCP tool is an external observer — it controls the browser from outside via Puppeteer or CDP and only works in Chrome. Feedthrough is an embedded agent. It runs *inside* the page, so it sees:

• Framework internals (React component trees, Redux store, custom globals)
• Any browser, not just Chrome
• Your existing dev workflow — no separate controlled browser to launch
• Cypress's own browser context during test runs

---

Packages

---

Framework support

---

Quick start

1. Start the MCP server

npx @feedthrough/mcp

The server listens for browser connections on ws://127.0.0.1:8765 and exposes MCP tools on stdio. Override the port with FEEDTHROUGH_PORT=9000. If the port is already taken, the server steps up to the next free one rather than refusing to start — see Running several sessions at once.

2. Add it to your MCP client config

{

"mcpServers": { "feedthrough": { "command": "npx", "args": ["@feedthrough/mcp"] } } }

3. Inject the bridge into your page

Vite + React / Vue / Solid / Preact:

// vite.config.ts

import { feedthrough } from "@feedthrough/vite"; export default defineConfig({ plugins: [feedthrough()] });

Next.js:

// next.config.ts

import { withFeedthrough } from "@feedthrough/nextjs"; export default withFeedthrough()({ /* your next config */ });

Nuxt 3:

// nuxt.config.ts

export default defineNuxtConfig({ modules: ["@feedthrough/nuxt"] });

SvelteKit:

// src/hooks.server.ts

import { feedthroughHandle } from "@feedthrough/sveltekit"; import { sequence } from "@sveltejs/kit/hooks"; export const handle = sequence(feedthroughHandle);

Remix:

// vite.config.ts

import { feedthrough } from "@feedthrough/remix"; export default defineConfig({ plugins: [remix(), feedthrough()] });

Webpack:

// webpack.config.mjs

import { FeedthroughPlugin } from "@feedthrough/webpack"; export default { plugins: [new FeedthroughPlugin()] };

Cypress:

// cypress/support/e2e.ts

import { setupFeedthrough } from "@feedthrough/cypress"; setupFeedthrough();

Playwright:

// import test from the adapter instead of @playwright/test

import { test, expect } from "@feedthrough/playwright";

Or manually (any bundler):

// main.ts

if (import.meta.env.DEV) { import("@feedthrough/core").then(({ init }) => init()); }

4. Open your page and start asking

Once the bridge connects you'll see [feedthrough] tab connected in the MCP server output. For the simplest experience, keep a single tab open. Multiple tabs can connect at the same time and commands are routed to the most recently active one, but a single tab avoids any ambiguity.

Then ask your AI agent:

> What's on the page right now?

Click the submit button and tell me what network requests fired

Why is the counter showing the wrong value?

---

MCP tools

Live edit is a preview, not a save. set_style / set_attribute / set_text mutate the running DOM so the agent can show you a fix without a rebuild. They are *not* written to your source and reset on reload/HMR. The loop: the agent previews live, you confirm, then it edits the actual source to make it stick. Changes a framework owns (text, controlled attributes) may be overwritten on the next render — the tool result flags this so the agent can tell you.

---

Example app

examples/react-app is a small React app with three deliberate bugs — a good sandbox for trying out the diagnostic workflow:

# Terminal 1 — app

cd examples/react-app && pnpm dev # http://localhost:5173

Terminal 2 — MCP server

cd packages/mcp && node dist/index.js

Connect an AI agent and ask it to find what's wrong. The three bugs are all invisible from the UI but findable in under a minute via get_console_logs, get_network_requests, and query_dom.

---

Running several sessions at once

Two AI agent sessions on one machine each start their own Feedthrough MCP server, and only one of them can have port 8765. That is handled, but it is worth knowing how.

The server moves, and tells you where it went. On a busy port it steps up (8766, 8767, …) instead of failing. connection_status() reports the port it actually bound, and the agent passes that to the dev server it starts:

FEEDTHROUGH_PORT=8766 npm run dev

Every build-tool adapter — vite, webpack, nextjs, nuxt, sveltekit, remix — reads FEEDTHROUGH_PORT (or FEEDTHROUGH_URL for a full ws:// URL) in Node at config-load time and bakes the result into the injected bridge. So a committed, argument-free feedthrough() pairs correctly in any session, with no file edits. An explicit serverUrl option always wins over the environment.

If you start the dev server yourself, the environment is unset and the page falls back to 8765, which may be another session's server. Either export the port before starting it, or pin one per project (below).

Pinning a port per project. For a project you always work on in its own session, pin the port on both ends and neither has to think about it. In .mcp.json:

{

"mcpServers": { "feedthrough": { "command": "npx", "args": ["@feedthrough/mcp"], "env": { "FEEDTHROUGH_PORT": "8770" } } } }

and in the app's config, feedthrough({ serverUrl: "ws://localhost:8770" }).

Telling bridges apart. Each server picks a readable name at startup (quiet-olive-heron) and sends it to every page that connects. The page logs one line to 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(). Two different names mean the tab is paired with another session's server — so "am I driving the right app?" is one call, not something you notice by watching the wrong window change.

---

Using with an AI agent

Recommended workflow

1. connection_status() — confirm the bridge is connected before anything else
2. get_console_logs() — errors and app output often identify the root cause immediately
3. get_network_requests() — look for failed fetches, wrong URLs, or missing calls
4. query_dom(selector) — find elements and check what's rendered
5. inspect_element(selector) — deep-dive on a specific element