The authenticated browser MCP — why cloud tools can't see your logged-in state

ation. Uses the local browser session.", { url: z.string().url().describe("Target URL within allowed domains"), selector: z.string().describe("CSS selector for data extraction"), maxRetries: z.number().optional().default(3), }, async ({ url, selector, maxRetries }) => { try { await this.ensureBrowser(); await this.validateSession();

      const page = await this.browser!.newPage();
      await page.goto(url, { waitUntil: "networkidle0" });
      
      // Wait for selector with timeout
      await page.waitForSelector(selector, { timeout: 10000 });
      
      const data = await page.evaluate((sel) => {
        const elements = document.querySelectorAll(sel);
        return Array.from(elements).map((el) => el.textContent?.trim());
      }, selector);

      await page.close();
      
      return {
        content: [{ type: "text", text: JSON.stringify(data) }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error: ${error.message}` }],
        isError: true,
      };
    }
  }
);

}

private async ensureBrowser(): Promise<void> { if (this.browser) return;

try {
  this.browser = await puppeteer.connect({
    browserURL: this.config.cdpEndpoint,
    defaultViewport: null,
  });
} catch (error) {
  throw new Error(
    "Failed to connect to local browser. Ensure Chrome is running with --remote-debugging-port."
  );
}

}

private async validateSession(): Promise<void> { const page = await this.browser!.newPage(); await page.goto(this.config.sessionValidationUrl, { waitUntil: "networkidle0", });

const url = page.url();
await page.close();

// Check if redirected to login page
if (url.includes("/login") || url.includes("/auth")) {
  throw new Error(
    "Session expired or invalid. Please re-authenticate in your browser and retry."
  );
}

}

async start(): Promise<void> { const transport = new StdioTransport(); await this.server.connect(transport); console.error("Local Authenticated Browser MCP started."); } }

// Usage const config: LocalBrowserConfig = { cdpEndpoint: "http://127.0.0.1:9222", allowedDomains: ["admin.shopify.com", "app.hubspot.com"], sessionValidationUrl: "https://admin.shopify.com/api/2023-01/shop.json", };

const bridge = new AuthenticatedBrowserBridge(config); bridge.start().catch(console.error);

#### Rationale

*   **Puppeteer-core vs. Puppeteer:** Using `puppeteer-core` avoids downloading a bundled Chromium. This ensures the server connects to the user's actual Chrome installation, preserving the exact fingerprint and session state.
*   **Session Validation:** The `validateSession` method checks for redirection to login pages. This prevents the agent from wasting tokens on failed requests and provides clear feedback to the user.
*   **Allowed Domains:** Restricting tools to specific domains mitigates the risk of the agent accessing unintended resources.
*   **Stdio Transport:** This keeps all communication local. The agent process and the MCP server communicate via standard streams, eliminating network exposure.

### Pitfall Guide

Implementing local-first browser automation introduces unique challenges. The following pitfalls are common in production environments.

1.  **Profile Contamination**
    *   *Explanation:* Reusing the user's default profile may expose the agent to extensions, bookmarks, or state that interferes with automation. Extensions like ad blockers or password managers can alter DOM structures or block requests.
    *   *Fix:* Use a dedicated Chrome profile for automation. Launch Chrome with `--user-data-dir` pointing to a clean directory, or use a separate profile slot. Disable unnecessary extensions in that profile.

2.  **CDP Security Exposure**
    *   *Explanation:* Chrome DevTools Protocol provides full control over the browser. If the CDP endpoint is exposed to the network, malicious actors could hijack the session.
    *   *Fix:* Always bind the CDP endpoint to `127.0.0.1`. Never expose CDP ports to `0.0.0.0`. Use firewall rules to restrict access to localhost only.

3.  **Session Drift and Stale State**
    *   *Explanation:* Sessions may expire during long-running agent tasks. The agent might attempt actions with an expired token, leading to inconsistent results.
    *   *Fix:* Implement periodic session health checks. Tools should validate session state before critical operations. Design workflows to handle `SessionExpired` errors gracefully, prompting the user to refresh the session.

4.  **Extension Interference**
    *   *Explanation:* Browser extensions can inject scripts or modify network requests, causing selectors to fail or data to be corrupted.
    *   *Fix:* Run automation in a profile with extensions disabled. If extensions are required, test thoroughly and add robust error handling for DOM variations caused by extension injection.

5.  **2FA Deadlocks**
    *   *Explanation:* If a session requires re-authentication with 2FA, the agent cannot proceed. The workflow hangs waiting for a response that will never come.
    *   *Fix:* Detect 2FA challenges (e.g., specific URLs or DOM elements). Return a structured error to the agent indicating that human intervention is required. The agent can then notify the user to approve the login manually.

6.  **Resource Leaks**
    *   *Explanation:* Opening multiple pages or contexts without closing them can exhaust browser resources, leading to crashes or performance degradation.
    *   *Fix:* Ensure every `page.open()` has a corresponding `page.close()`. Use `try/finally` blocks to guarantee cleanup. Monitor browser memory usage in long-running sessions.

7.  **Credential Leakage in Logs**
    *   *Explanation:* Debug logs may inadvertently capture cookies, tokens, or sensitive page content.
    *   *Fix:* Implement log redaction. Filter out headers containing `Authorization`, `Cookie`, or `Set-Cookie`. Avoid logging page content that may contain PII or secrets. Use structured logging with sensitive fields masked.

### Production Bundle

#### Action Checklist

- [ ] **Define Scope:** Identify which domains and workflows require authenticated access. Restrict MCP tools to these scopes.
- [ ] **Secure Transport:** Configure the MCP server to use `stdio` transport. Verify no network ports are exposed.
- [ ] **Profile Isolation:** Set up a dedicated Chrome profile for automation. Disable extensions and clear unnecessary state.
- [ ] **Session Validation:** Implement health checks that verify session validity before executing actions. Handle expiration gracefully.
- [ ] **Error Handling:** Design tools to return structured errors for auth failures, 2FA requirements, and network issues.
- [ ] **Log Redaction:** Audit logs to ensure no sensitive data (cookies, tokens, PII) is recorded.
- [ ] **Resource Management:** Implement strict cleanup routines for pages and contexts. Monitor browser resource usage.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Public Web Scraping** | Cloud MCP / Crawler | No auth required. Cloud offers scalability and IP rotation. | Low (Cloud compute costs) |
| **Internal Dashboard Analysis** | Local MCP Bridge | Requires session state. Local execution preserves auth and privacy. | Low (Local compute) |
| **High-Frequency API Calls** | Direct API Integration | Browser automation is slow. Use APIs where available. | Medium (API rate limits) |
| **Legacy Web Apps (No API)** | Local MCP Bridge | Only browser automation can interact with legacy UIs. Local preserves session. | Low (Local compute) |
| **Multi-Account Workflows** | Local MCP with Profile Switching | Requires managing multiple sessions. Local profiles allow isolation. | Medium (Complexity) |

#### Configuration Template

Use this template to configure your MCP client to connect to the local authenticated browser server.

```json
{
  "mcpServers": {
    "local-auth-browser": {
      "command": "node",
      "args": ["path/to/your/authenticated-browser-bridge.js"],
      "env": {
        "CDP_ENDPOINT": "http://127.0.0.1:9222",
        "SESSION_VALIDATION_URL": "https://admin.shopify.com/api/2023-01/shop.json",
        "ALLOWED_DOMAINS": "admin.shopify.com,app.hubspot.com"
      },
      "transport": "stdio"
    }
  }
}

Quick Start Guide

1. Launch Chrome with Debugging: Start Chrome with remote debugging enabled:

   open -a "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/automation-profile
   

2. Deploy Bridge: Install the AuthenticatedBrowserBridge package and configure the mcpServers JSON in your agent configuration.
3. Verify Session: Open the target application (e.g., Shopify) in the launched Chrome profile and ensure you are logged in.
4. Test Tool: Instruct your agent to use the extract_authenticated_data tool. Verify that the agent can access the authenticated content without login prompts.
5. Monitor: Check agent logs for session validation results and ensure no sensitive data is exposed.

By adopting a local-first architecture for authenticated browser automation, teams can unlock the full potential of AI agents for internal workflows while maintaining strict security and compliance standards. This approach bridges the gap between agent capabilities and the reality of modern web authentication.