docs/guides/mcp-agents.md

Using PinchTab with AI Agents (MCP)

This guide walks through setting up PinchTab as an MCP tool server for AI coding assistants and agent frameworks.

What is MCP?

The Model Context Protocol is an open standard for connecting AI models to external tools. PinchTab implements an MCP server that exposes 21 browser-control tools — navigation, interaction, screenshot, PDF export, and more — over a simple stdio interface that every major AI client supports.

Prerequisites

• PinchTab installed (pinchtab --version)
• Chrome installed and on PATH (or pointed to via config)
• An MCP-compatible client: Claude Desktop, VS Code with GitHub Copilot, or Cursor

Step 1: Start PinchTab

The MCP server is a thin adapter — it needs a running PinchTab instance to delegate to.

Headless mode (recommended for agents):

pinchtab bridge --headless

Normal server mode (if you want the dashboard too):

pinchtab

PinchTab listens on http://127.0.0.1:9867 by default.

Step 2: Configure Your MCP Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pinchtab": {
      "command": "pinchtab",
      "args": ["mcp"],
      "env": {
        "PINCHTAB_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop. You should see PinchTab in the tool list.

VS Code / GitHub Copilot

Create .vscode/mcp.json in your workspace root:

{
  "servers": {
    "pinchtab": {
      "type": "stdio",
      "command": "pinchtab",
      "args": ["mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "pinchtab": {
      "command": "pinchtab",
      "args": ["mcp"]
    }
  }
}

Any SDK-based Agent

# Python example using the mcp SDK
import subprocess, mcp

proc = subprocess.Popen(
    ["pinchtab", "mcp"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
)
# pass proc.stdin / proc.stdout to your MCP client transport

Environment Variables

Variable	Default	Description
PINCHTAB_TOKEN	(from config)	Bearer token for auth-protected servers

For remote servers, use the --server flag: pinchtab --server http://remote:9867 mcp

PINCHTAB_TOKEN can be found in ~/.config/pinchtab/config.yaml under server.token, or by running pinchtab config show.

Typical Agent Workflow

A well-written agent prompt would use tools in this order:

1. pinchtab_navigate        → go to the target URL
2. pinchtab_snapshot        → understand the page structure (find refs)
3. pinchtab_click / type    → interact with elements by ref
4. pinchtab_snapshot        → confirm state after interaction
5. pinchtab_get_text / pdf  → extract or export results

Example: Fill a Search Form

Agent: Search for "climate change" on Wikipedia

Tools called:
  pinchtab_navigate url="https://www.wikipedia.org"
  pinchtab_snapshot interactive=true
    → ...input[ref=e3] placeholder="Search Wikipedia"...
  pinchtab_click ref="e3"
  pinchtab_type  ref="e3" text="climate change"
  pinchtab_press key="Enter"
  pinchtab_snapshot compact=true
  pinchtab_get_text

Enabling JavaScript Evaluation

pinchtab_eval is disabled by default as a security measure. To enable it:

pinchtab config set security.allowEvaluate true

Or in ~/.config/pinchtab/config.yaml:

security:
  allowEvaluate: true

Restart PinchTab after changing this setting.

Warning: Enabling evaluate allows the agent (and any page it visits) to run arbitrary JavaScript in the browser. Only enable this on trusted networks with a token set.

Connecting to a Remote PinchTab

If PinchTab is running on another machine (e.g. a Docker container), use the --server flag:

{
  "mcpServers": {
    "pinchtab": {
      "command": "pinchtab",
      "args": ["--server", "http://192.168.1.50:9867", "mcp"],
      "env": {
        "PINCHTAB_TOKEN": "your-secure-token"
      }
    }
  }
}

The pinchtab mcp process runs locally (on the agent machine) and makes HTTP calls to the remote PinchTab instance. Chrome is on the remote machine — only the stdio MCP transport is local.

Troubleshooting

"Connection refused" from all tools

PinchTab is not running, or is on a different port. Check:

curl http://127.0.0.1:9867/health

"HTTP 401" from tools

Token mismatch. Set PINCHTAB_TOKEN to match server.token in your PinchTab config.

"HTTP 403" from pinchtab_eval

JavaScript evaluation is disabled. See Enabling JavaScript Evaluation above.

"ref not found" errors

Element refs change after every navigation or significant DOM update. Always call pinchtab_snapshot again after a page change before using refs from a previous snapshot.

MCP server not appearing in client

• Check the command value — pinchtab must be on PATH, or use an absolute path.
• Run pinchtab mcp manually in a terminal to check for startup errors.
• Check stderr output from the MCP process (client-specific, often in a log file).

Related Pages

• MCP Overview
• MCP Tool Reference
• MCP Architecture
• Security Guide