Cookie Authentication Guide

🎉 NEW: Browser Extension Cookie Support

BrowserLoop now directly supports cookie formats exported from browser extensions! No manual editing required.

✅ Direct Browser Extension Import

If you export cookies using browser extensions like Cookie Editor, EditThisCookie, or similar tools, you can use the exported JSON directly:

[
  {
    "name": "__Host-next-auth.csrf-token",
    "value": "actual-token-value",
    "domain": "app.example.com",
    "path": "/",
    "expires": -1,
    "httpOnly": true,
    "secure": true,
    "sameSite": "Lax"
  },
  {
    "name": "__Secure-next-auth.session-token",
    "value": "eyJhbGciOiJkaXIi...",
    "domain": "app.example.com",
    "path": "/",
    "expires": 1750704030.825311,
    "httpOnly": true,
    "secure": true,
    "sameSite": "Lax"
  }
]

✅ What BrowserLoop automatically handles:

✅ Session cookies (expires: -1) work correctly
✅ Float timestamps (like 1750704030.825311) are handled properly
✅ All security attributes (httpOnly, secure, sameSite) are respected
✅ Cookie prefixes (__Host-, __Secure-) work with proper security enforcement
✅ Domain validation follows RFC 6265 (parent domain cookies supported)

💡 Usage:

# Save browser extension export as cookies.json
export BROWSERLOOP_DEFAULT_COOKIES="/path/to/cookies.json"

# Or use directly in MCP requests (pass the JSON array)

Overview

BrowserLoop supports cookie-based authentication for capturing screenshots of login-protected pages during development. This is especially useful for testing authenticated areas of your applications.

Quick Start

Basic Usage

{
  "url": "https://localhost:3000/dashboard",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123xyz",
      "domain": "localhost"
    }
  ]
}

Default Cookies Configuration

Set default cookies in your MCP configuration for persistent authentication:

Method 1: JSON File (Recommended)

Create a JSON file with your cookies:

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  },
  {
    "name": "csrf_token",
    "value": "your-csrf-token-here",
    "domain": "localhost",
    "path": "/admin"
  }
]

Then reference the file in your MCP configuration:

{
  "mcpServers": {
    "browserloop": {
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json"
      }
    }
  }
}

Method 2: JSON String (Legacy)

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"dev_session\",\"value\":\"your_session_value\",\"domain\":\"localhost\"}]"
      }
    }
  }
}

Benefits of File Path Method:

✅ Easy to edit - Use your editor with JSON syntax highlighting
✅ No escaping - No need to escape quotes in JSON
✅ Version control - Can version control your cookie files
✅ Validation - Easy to validate JSON syntax
✅ Readable - Much cleaner MCP configuration

Development Use Cases

Local Development Server

Testing your app's authenticated routes:

// Extract cookies from your dev environment
{
  "url": "https://localhost:3000/admin/dashboard",
  "cookies": [
    {
      "name": "connect.sid",
      "value": "s:your-session-id.signature",
      "domain": "localhost"
    }
  ]
}

Staging Environment

{
  "url": "https://staging.example.com/protected-area",
  "cookies": [
    {
      "name": "auth_token",
      "value": "eyJhbGciOiJIUzI1NiIs...",
      "domain": "staging.example.com",
      "secure": true
    }
  ]
}

API Documentation Tools

Testing tools like Swagger UI or GraphQL Playground:

{
  "url": "https://localhost:4000/graphql",
  "cookies": [
    {
      "name": "graphql_session",
      "value": "dev_token_123",
      "domain": "localhost"
    }
  ]
}

Cookie Extraction for Development

Method 1: Browser Dev Tools

Login to your development app in your browser
Open Developer Tools (F12)
Go to Application tab → Cookies → localhost (or your domain)
Copy the session cookie values

Method 2: Browser Console

Run this in your browser console on your development site:

// Extract all cookies for current domain
JSON.stringify(
  document.cookie.split(';').map(cookie => {
    const [name, value] = cookie.trim().split('=');
    return {
      name: name,
      value: value,
      domain: window.location.hostname
    };
  }).filter(c => c.name && c.value)
);

Method 3: From Network Tab

Open Network tab in dev tools
Make a request to your authenticated endpoint
Check request headers for Cookie header
Copy the cookie values

Cookie Formats

Array of Objects (Recommended)

{
  "url": "https://localhost:3000/admin",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": "localhost"
    },
    {
      "name": "csrf_token",
      "value": "xyz789",
      "domain": "localhost",
      "path": "/admin"
    }
  ]
}

JSON String

{
  "url": "https://localhost:3000/admin",
  "cookies": "[{\"name\":\"session_id\",\"value\":\"abc123\",\"domain\":\"localhost\"}]"
}

Cookie Properties

Property	Required	Description	Example
`name`	✅	Cookie name	`"session_id"`
`value`	✅	Cookie value	`"abc123xyz"`
`domain`	❌	Domain (auto-derived from URL)	`"localhost"`
`path`	❌	Path (defaults to "/")	`"/admin"`
`secure`	❌	HTTPS only	`true`
`httpOnly`	❌	HTTP only	`true`

Common Development Scenarios

Express.js with express-session

// Typical Express session cookie
{
  "name": "connect.sid",
  "value": "s:session-id.signature",
  "domain": "localhost"
}

JWT Authentication

// JWT stored in cookie
{
  "name": "jwt_token",
  "value": "eyJhbGciOiJIUzI1NiIs...",
  "domain": "localhost",
  "httpOnly": true
}

Custom Auth Cookie

// Custom authentication cookie
{
  "name": "auth_session",
  "value": "user123_authenticated",
  "domain": "localhost"
}

Development with Docker

// When your app runs in Docker
{
  "url": "https://localhost:8080/dashboard",
  "cookies": [
    {
      "name": "docker_session",
      "value": "container_session_123",
      "domain": "localhost"
    }
  ]
}

Troubleshooting

Common Issues

Screenshots show login page instead of authenticated content

Solutions:

Check cookie expiration - Re-login and extract fresh cookies
Verify domain matches - Use exact domain from URL
Include all required cookies - Some apps need multiple cookies

"Cookie validation failed" error

Solutions:

Fix domain mismatch:

// ✅ Correct for localhost:3000
"domain": "localhost"

// ❌ Wrong
"domain": "localhost:3000"

Check JSON format:

// ✅ Valid JSON
"[{\"name\":\"session\",\"value\":\"123\"}]"

// ❌ Invalid JSON
"[{name:session,value:123}]"

Debug Mode

Enable debug logging to see cookie injection details:

export BROWSERLOOP_DEBUG=true

Monitor debug logs:

tail -f /tmp/browserloop.log

Debug logs include:

Cookie loading and merging process
Automatic file watching and refresh events
Cookie injection and domain validation
Screenshot operation details

Note: Logs are written to /tmp/browserloop.log (not console) for MCP compatibility.

Security Notes

Development Best Practices

Use localhost/staging cookies only - Never use production cookies
Rotate development sessions - Refresh cookies regularly
Environment isolation - Keep dev/staging/prod cookies separate
Use HTTPS in staging - Match production security settings

Cookie Safety

✅ Local development cookies are safe to use
✅ Staging environment cookies are acceptable for testing
❌ Production cookies should never be used for screenshots
❌ Personal account cookies should not be shared

Example: Full Development Workflow

1. Extract Development Session

# Login to your dev app at https://localhost:3000
# Open dev tools and copy session cookie

2. Configure Default Cookie

Create a cookies file:

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

Reference in MCP configuration:

{
  "mcpServers": {
    "browserloop": {
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json"
      }
    }
  }
}

3. Test Authenticated Pages

Take a screenshot of https://localhost:3000/admin/users
Take a screenshot of https://localhost:3000/dashboard
Take a screenshot of https://localhost:3000/settings

All requests automatically include your development session cookie!

For more details, see the main API documentation.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!