forge

A CLI and MCP server suite for Intercom workspace management and automation: migrations, workspace configuration, routing, Fin AI content, and workflow authoring. Ships two MCP servers — forge-workspace (workspace config: articles, teams, tickets, macros, attributes, …) and forge-fin (Fin AI agent, Voice, knowledge sources, workflows) — plus the forge CLI for machine setup.

Requirements

• Python 3.11+
• Google Chrome — UI-automation tools drive your own Chrome over the DevTools Protocol. No bundled browser is downloaded, ever.
• An Intercom access token per workspace you manage (Developer Hub → your app → Authentication).
• A forge license key.

Install

uv tool install sabel-forge-mcp        # recommended
# or: pipx install sabel-forge-mcp
# or: pip install sabel-forge-mcp

Everything is included — REST tools and UI-automation tools work out of the box. There are no extras to opt into and no playwright install browser download (Playwright ships as a plain dependency and is only used as the connection library to your own Chrome).

Verify:

forge --version        # → forge (sabel-forge-mcp) x.y.z

Then activate your license:

forge auth login

Upgrading from ≤ 0.1.63? forge install ui-deps and the [ui-automation] extra are gone — a plain install/upgrade now carries everything: uv tool upgrade sabel-forge-mcp.

Configure a workspace

Each Intercom workspace is a folder under ~/.forge/workspaces/ holding a forge.json. The file names the environment variable that holds the workspace's token — never the token itself (inline tokens are rejected):

// ~/.forge/workspaces/Client_Acme/forge.json
{
  "name": "Client_Acme",
  "industry": "fintech",          // optional; matches a playbook name
  "region": "eu",                 // us | eu | au — the Intercom datacenter
  "deployment": "intercom",       // intercom (full suite) | fin_for_salesforce | fin_for_zendesk | ... — auto-detected if omitted
  "intercom_token_env": "CLIENT_ACME_TOKEN"
}

Put the token in ~/.secrets (chmod 600, sourced from your shell rc):

export CLIENT_ACME_TOKEN="tok:..."

region matters: REST reads work from anywhere, but REST writes and all admin-UI automation are datacenter-specific. If omitted, forge auto-detects it on first use and writes it back into forge.json.

You can also let your agent do all of this — the add_workspace MCP tool walks through the same steps and validates the token and region.

Wire up the MCP servers

For Claude Code:

claude mcp add forge-workspace -- forge-workspace
claude mcp add forge-fin -- forge-fin

Launch your agent once at any directory; every tool takes a workspace argument, so one server process serves all configured workspaces. After adding a new token to ~/.secrets, restart the agent so the servers inherit the new environment.

UI automation and the Chrome host

Tools ending in _via_ui drive the Intercom admin UI (for resources with no write REST API). They run exclusively as tabs in one long-lived Google Chrome bound to a local DevTools port:

• The first *_via_ui run auto-starts the host — a Chrome window opens, you log into Intercom once, and the login persists on disk.

• Manage it explicitly if you prefer:

  forge ui serve --workspace <name>   # start manually; log in once
  forge ui status                     # endpoint, workspace, region
  forge ui stop                       # shut it down
  

• The browser survives tool failures — a failed run leaves the page open for inspection, and re-running a tool resumes idempotently.

• One browser can hold logins for several Intercom datacenters; a tool targeting a different region opens a fresh login tab and tells you.

Unlocked mode (advanced, opt-in)

The admin UI talks to private /ember/... endpoints. Unlocked mode lets forge replay verified /ember calls directly from the logged-in Chrome host instead of clicking through the UI — faster and less brittle, but the endpoints are undocumented and unsupported by Intercom, so the mode is off by default:

forge unlocked on|off|status        # persistent toggle (~/.forge/unlocked.json)
FORGE_UNLOCKED=1 ...                # per-run override
forge ui capture --workspace <name> # record the UI's own /ember calls while you click

Ember-backed tools (currently workflow-ruleset audience repair and "Set live") refuse to run while locked. Coverage grows by capturing a real UI action with forge ui capture, then replaying it; pre-change backups land in ~/.forge/ember_backups/.

Upgrading

uv tool upgrade sabel-forge-mcp      # or: pipx upgrade sabel-forge-mcp

The MCP servers check PyPI in the background and mention when a newer release is available.