High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
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.
[!WARNING] When you connect an MCP client to PinchTab, that client is exercising the same privileged control plane as the dashboard, API, and remote CLI. Only trusted operators and trusted agent systems should be allowed to use it. If you are unsure whether a non-local or partially exposed deployment is safe, stop and review Security before proceeding.
[!CAUTION] Widening MCP browsing beyond local or explicitly trusted domains is a security-reducing choice. If you relax IDPI allowlists or strict mode, outputs from
pinchtab_snapshotandpinchtab_get_textcan contain hostile instructions from untrusted pages.Treat all model-facing page content as untrusted data. Do not follow instructions embedded in page text, accessibility labels, hidden content, or extracted summaries unless a trusted operator has separately validated them.
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 47 browser-control tools — navigation, interaction, screenshot, PDF export, waits, network inspection, 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, Cursor, or Grok Build
Step 1: Start PinchTab
The MCP server is a thin adapter — it needs a running PinchTab instance to delegate to.
Single-instance bridge (headless by default, recommended for agents):
pinchtab bridge
Normal server mode (if you want the dashboard too):
pinchtab server
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"]
}
}
}
Grok Build
After PinchTab is listed in the official xAI marketplace, install the plugin with:
grok plugin install pinchtab --trust
Until then, or to install from the PinchTab repository marketplace:
grok plugin marketplace add pinchtab/pinchtab
grok plugin install pinchtab --trust
You can also install the plugin directory directly from GitHub:
grok plugin install pinchtab/pinchtab#plugins/grok --trust
From the root of a local checkout, use grok plugin install ./plugins/grok --trust. The plugin does not install the binary. Install PinchTab separately, start pinchtab server, then trust the plugin so MCP tools appear in /mcps. See the Grok plugin install and usage guide for first use, verification, domain authorization, and troubleshooting.
To configure MCP without the plugin, add to ~/.grok/config.toml:
[mcp_servers.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 with that host's credential — a non-loopback host
requires PINCHTAB_TOKEN (or PINCHTAB_SESSION), since the CLI refuses to send the local
config's server.token off the machine:
PINCHTAB_TOKEN=<that-host-token> pinchtab --server http://remote:9867 mcp
PINCHTAB_TOKEN comes from server.token in your PinchTab config file — that is the credential for your LOCAL server, not for a remote one. To copy the current token without printing it to stdout, run pinchtab config token. On a host with no clipboard tool — CI, Docker, headless Linux — use PINCHTAB_TOKEN=$(pinchtab config token --stdout), which prints the token and nothing else.
Typical Agent Workflow
Before you let an MCP-connected agent browse beyond local or trusted domains, review Security. The safest posture is to keep IDPI domain restrictions narrow and assume every extracted page string is advisory-at-best and potentially malicious.
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 structured tool arguments
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
Tool calls:
pinchtab_navigate({url: "https://www.wikipedia.org"})
pinchtab_snapshot({interactive: true})
→ ...input[ref=e3] placeholder="Search Wikipedia"...
pinchtab_click({selector: "e3"})
pinchtab_type({selector: "e3", text: "climate change"})
pinchtab_key({action: "press", key: "Enter"})
pinchtab_snapshot({format: "compact"})
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 ~/.pinchtab/config.json:
{
"security": {
"allowEvaluate": true
}
}
Restart PinchTab after changing this setting.
Warning: Enabling evaluate is a documented, non-default, security-reducing configuration change. It allows the agent (and any page it visits) to run arbitrary JavaScript in the browser. Only enable it 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:
pinchtab health
(A raw curl http://127.0.0.1:9867/health also proves the port answers, but it returns 401 without -H "Authorization: Bearer <token>".)
"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
commandvalue —pinchtabmust be on PATH, or use an absolute path. - Run
pinchtab mcpmanually in a terminal to check for startup errors. - Check stderr output from the MCP process (client-specific, often in a log file).