@customaise/mcp

MCP server and CLI that connect AI coding agents to the Customaise Chrome extension. Manage UserScripts, build AgentScripts, call WebMCP tools inside the user's signed-in browser session, select DOM elements visually, and drive tabs. Drive it over stdio from an IDE, or as a customaise command from a shell.

21 tools, 5 resources plus a script resource template, WebSocket bridge between your agent and a real Chrome session, whichever door it arrives through.

Two ways in. customaise-mcp is the MCP server an IDE spawns over stdio. customaise is a CLI for agents that have a shell instead, driving the same tools through a resident daemon. Both go through the same cap enforcement and the same consent gate.

AI Agent ←(stdio)→ MCP Server ←(WebSocket)→ Customaise Extension

Speaks the MCP 2026-07-28 revision, negotiated per connection: a client on that revision gets the stateless flow with cacheable tools/list, and a client on the 2025 revisions keeps working unchanged. The package is 3.x precisely so nobody has to guess this from a 2.x version number.

Quick Start

1. Install Customaise

Install the Customaise Chrome extension on Chrome 147 or later, sign in, and turn on Agent Bridge in Settings → MCP & Terminal. Chrome 147 is the tested release baseline for extension 1.3.9.

2. Add to your IDE

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

Claude Code (one command, no file to edit):

claude mcp add customaise -- npx -y @customaise/mcp

Claude Desktop: install customaise.mcpb from the latest release. The bundle returns page content inline, which a chat client needs (see Chat clients and file-less agents). Or add it to claude_desktop_config.json with the same setting:

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"],
      "env": { "CUSTOMAISE_MCP_OUTPUT": "inline" }
    }
  }
}

Kiro (.kiro/mcp.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.customaise]
command = "npx"
args = ["-y", "@customaise/mcp"]

Antigravity (mcp_config.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

3. Done

Your agent can now read and edit UserScripts, build AgentScripts that expose WebMCP tools to it, select DOM elements visually, inspect the console, and take screenshots of the live tab.

Tools (21)

Script Lifecycle

| Tool | Description | |------|-------------| | list_scripts | List every script (UserScripts and AgentScripts) managed by the extension | | import_script | Pull a script to a local file for editing | | export_script | Push a local file to Customaise (validates and installs) | | delete_script | Permanently delete a script | | toggle_script | Enable or disable a script |

Browser Context

| Tool | Description | |------|-------------| | get_page_context | DOM snapshot of the current page | | get_console_context | Console logs, errors, and GM_log output | | list_tabs | List all open browser tabs |

Tab Control

| Tool | Description | |------|-------------| | open_tab | Open a new tab at a given URL | | close_tab | Close a tab by ID | | focus_tab | Switch focus to a tab by ID | | reload_tab | Reload a tab to re-inject scripts |

Visual DOM Targeting

| Tool | Description | |------|-------------| | get_selected_elements | Get the DOM elements the user has visually selected, with stable, tiered selectors and screenshots | | take_screenshot | Capture any tab (not just the visible one) as a viewport or full-page image |

WebMCP Agent Tools

| Tool | Description | |------|-------------| | list_webmcp_tools | List the WebMCP tools currently registered on a tab by AgentScripts | | call_webmcp_tool | Call a WebMCP tool; prompt-gated tools block on user consent (see below) |

UI Control & Batch

| Tool | Description | |------|-------------| | toggle_ui | Show or hide the Customaise UI overlay | | sync_scripts | Bulk export all scripts to a local directory |

Script Decisions

| Tool | Description | |------|-------------| | get_script_decisions | Read Script Decisions on this device: whether agents may manage it, saved provider keys, and each script's provider and state; with a script ID, its question lists and their hashes | | set_script_decisions | Choose a script's provider (Jev or Decisions API) and which question lists are On, or switch it off. Needs the person to turn on Script Decisions under Full access, except off |

Diagnostics

| Tool | Description | |------|-------------| | get_bridge_status | Report extension attachment, plan tier, sign-in, remaining quota and the browser's agent permission mode, including whether agents may manage Script Decisions, when supported. Costs no quota itself. |

Resources (5 plus a template)

Five resources and one script resource template that connected agents can read via resources/read. The two conventions handbooks define exactly how Customaise expects UserScripts and AgentScripts to be written. Agents should read the relevant handbook before touching a script.

| URI | Description | |-----|-------------| | customaise://scripts | Live JSON list of every script the extension manages (ID, name, enabled state, match patterns, shared flag) | | customaise://scripts/{scriptId} | Full source and metadata for a specific script | | customaise://conventions | Points at the right handbook for the script type you're working on | | customaise://userscript-conventions | Full UserScript reference: file structure, IIFE pattern, GM_* APIs, symbol-level editing, @match and @namespace rules | | customaise://agentscript-conventions | Full AgentScript reference: the // ==AgentScript== block, // @webmcp <tool> <permission> declarations, document.modelContext.registerTool(), consent model | | customaise://script-decisions | Shared UserScript/AgentScript guide: Decisions API questions, the CM_decisions API, working example, device/provider setup, billing and failure handling |

Script Decisions in UserScripts and AgentScripts

Script Decisions is a Power User capability and needs extension 1.3.8 or later. Read customaise://script-decisions over MCP or run:

customaise resource script-decisions

Use it for bounded text classification, relevance checks and scoring; use ordinary code for extraction, exact rules and actions. Both script engines declare @grant CM_decisions and call CM_decisions.create or createMany with Decisions API questions written out in the code. The resource contains a complete UserScript and instructions for wrapping the same helper in an AgentScript tool.

The user saves separate Jev/Decisions API keys on /account#script-decisions, enables the device in Your Devices (from another device when that browser is marked Operated by an AI agent), and selects a provider in the script's Decisions menu (its branch icon, or Quick Actions → Script Decisions). Requests then run automatically. Settings can pause the device without losing selections; Data & Analytics reports usage by device/provider. Provider charges and budgets are separate from Customaise browser AI tokens. MCP/CLI cannot supply keys or allow a device. WebMCP approval still applies independently to the containing tool.

create and createMany wait for the answers themselves. Preserve refusals and errors; do not resend uncertain work or switch providers automatically. Changing a script's code asks for its provider to be chosen again, unless an agent saved it under the grant below. See the Script Decisions guide.

Agents choosing providers

Settings → Agent permissions → Full access has a second part, Script Decisions. Only the person turns it on, through a protected confirmation in the extension; no MCP tool or CLI command can. While it is on, connected agents can choose a script's provider (Jev or Decisions API) on this device, switch its question lists On or Off, and resume a script the loop guard paused for repeating the same input (loop_repeat). Switching a script's provider off is always allowed. Provider keys, the device's Allow Script Decisions switch, daily limits, pausing the device, a runaway-loop pause (loop_runaway) and scripts shared with the person stay with the person; those refusals carry error type person_required (CLI exit 6), and the agent should tell the person the step rather than retry.

| MCP | CLI | |---|---| | get_script_decisions({ scriptId? }) | customaise decisions [id] | | set_script_decisions({ scriptId, provider, sets? }) | customaise decisions set <id> <jev\|openai-decisions\|off> [--sets HASH,HASH] |

sets names the question lists to switch On by the hashes get_script_decisions returns for one script; every other list goes Off. When an agent saves a script with export_script while Script Decisions is on for agents, Customaise signs its provider again for the new code if it was current for the code just replaced, and scriptDecisions in the result says whether it was kept and, if not, why. Without the grant the person chooses the provider again after the edit. Both tools need extension 1.4.0 or later; an older extension answers extension_outdated.

Updating to MCP/CLI 3.2.9 and extension 1.4.0

The CLI and Desktop bundle ship the same tested runtime dependencies. Runtime dependencies are bundled in the npm tarball so fresh installs retain those versions. Contributors should use npm ci; dependency updates belong in package-lock.json and must pass the packaged-release checks before publication.

Update both the extension and the companion for the latest permission controls and status reporting. The npm package contains both customaise-mcp and the customaise CLI; Claude Desktop uses the matching 3.2.9 .mcpb bundle. Restart all MCP clients and any running Customaise CLI daemon after updating. Relay protocol 2 is unchanged from 3.2.3. The tool surface grows to 21 with get_script_decisions and set_script_decisions.

The AgentScript handbook now teaches document.modelContext, the WebMCP standard name that extension 1.4.0 provides; navigator.modelContext still works in every version. Both handbooks note that Chrome withholds secure-context APIs on plain http pages other than localhost, and the UserScript handbook describes @connect as 1.4.0 reads it. Read customaise://agentscript-conventions or customaise://userscript-conventions, or run customaise resource <name>, before editing a script. The migration reference covers moving a library from Tampermonkey. Customaise provides every GM API and metadata key Tampermonkey supports on Chrome.

Agent permissions and Full access

Settings → Agent permissions offers Use tool permissions (the default) and Full access. A user-confirmed Full access grant lets eligible Prompt tools run without repeated Customaise approvals in that browser profile, including new and updated tools. Saved Deny rules, undeclared tools, disabled scripts and URL restrictions still apply. Saved per-tool choices are preserved; turning Full access off restores them. The grant stays on until disabled or the user signs out, is not synced, and does not enable Chrome DevTools access. Browsers configured to accept approvals only from another device cannot enable Full access locally.

`get_bridge_