MCP

playwright-mcp compatible

MCP Server Documentation

SiteGulp is a drop-in replacement for microsoft/playwright-mcp. Connect your AI assistant to SiteGulp as a remote MCP server and get all 22 browser_* tools from playwright-mcp — running in the cloud — plus 5 additional tools for AI-powered full-site crawling and analysis.

Get API Key Server Info REST API Docs

Drop-in replacement for microsoft/playwright-mcp

Already using playwright-mcp locally? Replace your local config with SiteGulp and move your browser automation to the cloud — no Playwright install needed on your machine.

Before (local playwright-mcp)

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

After (SiteGulp remote)

{
  "mcpServers": {
    "playwright": {
      "type": "http",
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_YOUR_KEY"
      }
    }
  }
}

All 22 browser_* tools work identically — same input/output schemas

Browser sessions are maintained server-side using Mcp-Session-Id headers

Plus 5 extra tools for AI full-site crawling (start_crawl, get_crawl_summary, etc.)

browser_file_upload requires server-side absolute file paths (not client paths)

How It Works

1Configure Once

Add SiteGulp to your AI tool's MCP config with your API key.

2Browser Automation

Use browser_* tools for interactive browsing — navigating, clicking, typing, taking screenshots.

3Full-Site Analysis

Use start_crawl + get_crawl_summary for AI-powered analysis of entire websites.

Suggested system prompt for your AI assistant:

You have access to the SiteGulp MCP server.

For interactive browser automation (clicking, typing, filling forms):
- Use browser_navigate, browser_snapshot, browser_click, browser_type, etc.
- Include the Mcp-Session-Id header to maintain session state across calls.

For full-site AI analysis:
1. Call create_or_get_project with the URL.
2. Call start_crawl with a descriptive prompt.
3. Poll get_crawl_status every 10 seconds until "completed".
4. Call get_crawl_summary to read all discovered pages.

Do not create duplicate projects for the same URL — always check if one exists first.

Browser Tools
playwright-mcp compatible

All 22 tools from microsoft/playwright-mcp with identical input/output schemas, running server-side on Chromium.

Tool	Description
`browser_navigate`	Navigate to a URL
`browser_snapshot`	Accessibility tree snapshot (better than screenshot for actions)
`browser_click`	Click an element by ref
`browser_type`	Type text into an element
`browser_take_screenshot`	Capture a viewport or full-page screenshot
`browser_evaluate`	Evaluate a JavaScript expression on the page
`browser_wait_for`	Wait for text, condition, or time
`browser_tabs`	List, create, close, or select tabs
`browser_fill_form`	Fill multiple form fields atomically
`browser_run_code`	Run arbitrary Playwright code (page function)
`browser_hover`	Hover over an element
`browser_drag`	Drag and drop between elements
`browser_select_option`	Select option(s) in a dropdown
`browser_press_key`	Press a keyboard key
`browser_navigate_back`	Go back in browser history
`browser_close`	Close the current tab
`browser_resize`	Resize the browser window
`browser_file_upload`	Upload files via a file chooser (server-side paths)
`browser_handle_dialog`	Accept or dismiss a browser dialog
`browser_network_requests`	Get all network requests since page load
`browser_console_messages`	Get console messages filtered by severity
`browser_install`	Ensure the browser binary is installed

SiteGulp Crawl Tools
SiteGulp exclusive

These 5 tools go beyond browser_* automation — they run a full AI-powered crawl of a website and return structured descriptions of every page.

`create_or_get_project`

Create a project for a website URL, or return the existing one. Idempotent — safe to call repeatedly. Create one project per website you work with.

Parameters: url (required), name (optional), description (optional)

`list_projects`

List all projects in your account with their last crawl status.

Parameters: limit (optional, default 20)

`start_crawl`

Start an AI-powered crawl of a project. The crawler navigates the site, takes screenshots, and generates descriptions of every page. Optionally generates Playwright automation scripts.

Parameters: project_id (required), name (required), prompt (required), include_images, include_videos, include_descriptions, include_design_improvements, include_browser_console_logs, viewport_desktop, viewport_tablet, viewport_mobile, record_script, record_script_language

`get_crawl_status`

Check the progress of a running crawl. Poll until status is "completed" or "failed".

Parameters: crawl_id (required)

`get_crawl_summary`

Get text descriptions of all crawled pages — URL, title, AI description, page type, forms, links. Everything needed to understand a site, no screenshots required.

Parameters: crawl_id (required), max_pages (optional, default 100)

Browser Session Management

The server maintains server-side browser sessions using the Mcp-Session-Id header (per the MCP Streamable HTTP spec). Each session has its own Chromium browser context with isolated tabs, cookies, and console/network buffers.

Session created on initialize

The server returns Mcp-Session-Id: <uuid> in the initialize response header. Include it in all subsequent requests.

Sessions auto-expire after 30 minutes of inactivity

The browser is closed and memory is freed. Call initialize again to start a new session.

Per-user fallback session

If no Mcp-Session-Id is provided, a stable per-user default session is used (keyed to your API key). Useful for simple single-browser workflows.

browser_file_upload limitation

File paths must exist on the server, not the client machine. This differs from local playwright-mcp where both are the same machine.

Session ID flow

bash

# 1. Initialize — get session ID
curl -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  -D -  # print response headers

# Response headers include:
# Mcp-Session-Id: 550e8400-e29b-41d4-a716-446655440000

# 2. Use session ID in subsequent requests
curl -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_YOUR_API_KEY_HERE" \
  -H "Mcp-Session-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"browser_navigate","arguments":{"url":"https://example.com"}}}'

Authentication

The MCP server uses your SiteGulp API key (Bearer token). Generate one from your Settings page.

Authorization header

http

Authorization: Bearer sk_your_api_key_here

initialize and tools/list work without auth

Your client can discover server capabilities before authenticating.

All tool calls require a valid API key

Include the Authorization header in your MCP client config.

Keep your key secret

Never commit API keys to version control. Use environment variables.

Client Configuration

Claude Code

~/.claude/settings.json

Add under "mcpServers". Restart Claude Code after saving.

{
  "mcpServers": {
    "sitegulp": {
      "type": "http",
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_YOUR_API_KEY_HERE"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json

Requires mcp-remote package. Install with: npm install -g mcp-remote

{
  "mcpServers": {
    "sitegulp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/api/mcp",
        "--header",
        "Authorization: Bearer sk_YOUR_API_KEY_HERE"
      ]
    }
  }
}

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

Add under "mcpServers" in your Cursor MCP config.

{
  "mcpServers": {
    "sitegulp": {
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_YOUR_API_KEY_HERE"
      }
    }
  }
}

OpenCode

opencode.json or ~/.config/opencode/config.json

Add under "mcp" section in your OpenCode config.

{
  "mcp": {
    "servers": {
      "sitegulp": {
        "type": "remote",
        "url": "http://localhost:3001/api/mcp",
        "headers": {
          "Authorization": "Bearer sk_YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

cURL (manual test)

Verify your setup from the command line

Use this to test the MCP server directly.

# Initialize (no auth needed)
curl -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# List tools (no auth needed)
curl -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Navigate a browser (auth required)
curl -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_YOUR_API_KEY_HERE" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_navigate","arguments":{"url":"https://example.com"}}}'

# Create a crawl project (auth required)
curl -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_YOUR_API_KEY_HERE" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"create_or_get_project","arguments":{"url":"https://example.com"}}}'

Typical LLM Workflows

Interactive browser automation (playwright-mcp style)

Example browser automation sequence

json

// Step 1: Navigate to a page
{"method":"tools/call","params":{"name":"browser_navigate","arguments":{"url":"https://myapp.example.com"}}}
// → {"content":[{"type":"text","text":"Navigated to https://myapp.example.com\nPage title: My App"}]}

// Step 2: Take an accessibility snapshot to find element refs
{"method":"tools/call","params":{"name":"browser_snapshot","arguments":{}}}
// → {"content":[{"type":"text","text":"- document\n  - heading \"My App\" [level=1]\n  - button \"Sign In\" [ref=e42]"}]}

// Step 3: Click a button using its ref
{"method":"tools/call","params":{"name":"browser_click","arguments":{"ref":"e42","element":"Sign In button"}}}
// → {"content":[{"type":"text","text":"Clicked element ref=\"e42\""}]}

// Step 4: Take a screenshot
{"method":"tools/call","params":{"name":"browser_take_screenshot","arguments":{"type":"png"}}}
// → {"content":[{"type":"image","data":"...base64...","mimeType":"image/png"}]}

Full-site AI crawl (SiteGulp exclusive)

json

// Step 1: Create or find project
{"method":"tools/call","params":{"name":"create_or_get_project","arguments":{"url":"https://myapp.example.com","name":"My App"}}}
// → {"project_id": "proj_abc123", "status": "created", ...}

// Step 2: Start a crawl (with optional content options + script recording)
{"method":"tools/call","params":{"name":"start_crawl","arguments":{"project_id":"proj_abc123","name":"Initial crawl","prompt":"Document all pages, forms, and navigation patterns","include_images":true,"include_descriptions":true,"include_browser_console_logs":true,"record_script":true,"record_script_language":"javascript"}}}
// → {"crawl_id": "crl_xyz789", "status": "pending", ...}

// Step 3: Poll until done (every ~10s)
{"method":"tools/call","params":{"name":"get_crawl_status","arguments":{"crawl_id":"crl_xyz789"}}}
// → {"status": "running", "progress_percent": 42, "pages_found": 18, ...}

// Step 4: Read results once complete
{"method":"tools/call","params":{"name":"get_crawl_summary","arguments":{"crawl_id":"crl_xyz789"}}}
// → {"pages": [{"url":"/", "title":"Home", "description":"Landing page with hero and CTA..."}, ...]}

Endpoint Reference

POST

/api/mcp

Main MCP endpoint. Send JSON-RPC 2.0 requests here. Include Mcp-Session-Id for session-aware browser tools.

GET