SoftGlaze AI: connect your AI app | SoftGlaze Browser docs

Turn on SoftGlaze AI, create a token and connect Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, Codex, Windsurf, Cline or n8n. Then approvals, Stop all AI, memories, automation tokens and troubleshooting.

SoftGlaze AI is a Model Context Protocol (MCP) server inside SoftGlaze Browser. An AI app that speaks MCP connects to it and gets 40 tools: it can read your profiles, proxies and activity, check proxy health, start and stop profiles, run macros and work inside the pages of a running profile. Every profile it touches keeps its own proxy and fingerprint. Anything that changes something waits until you allow it in SoftGlaze.

This guide covers every step, with the exact setup the app gives you for each AI app. More pages go with it: the prompt library, the tool reference, the installs for Claude Desktop, Cowork and Claude Code, and Playwright MCP and Chrome DevTools MCP for experts.

Using Claude Desktop or Cowork? Download the SoftGlaze extension for Claude Desktop (softglaze-browser.mcpb, version 1.0.0, 68 KB; SHA-256 in the .sha256 file), double-click it and paste your token. The steps are in Install in Claude Desktop.

Before you start

It is a Beta, in version 1.0.22 and later. SoftGlaze AI ships as a Beta in SoftGlaze Browser 1.0.22. If your app has no SoftGlaze AI page, update it from the download page; the Microsoft Store copy can trail the download by a few days. Tools, prompts and setups may still change before the full release.
It runs on your computer only. The server answers on 127.0.0.1 and nowhere else, so the AI app has to run on the same Windows computer as SoftGlaze. AI apps that live only on the web (ChatGPT on the web, Grok) and n8n Cloud can’t reach it yet. They need the Cloud Relay, which comes after the Beta.
You need the Owner or an Admin. Only they can open the SoftGlaze AI page, turn it on and create tokens.
SoftGlaze has to be open. The server lives inside the app. Close the app and every AI app loses its connection until you open it again.

How the pieces fit:

Your AI app  --MCP-->  http://127.0.0.1:<PORT>/mcp  -->  SoftGlaze Browser  -->  your profiles
(Claude, Cursor,          on this computer only            asks you before          each with its own
 Codex, n8n ...)                                           every change             proxy and fingerprint

Turn on SoftGlaze AI

Open SoftGlaze Browser and choose SoftGlaze AI in the sidebar, under Workspace. It carries a Beta label.
Switch on AI server at the top of the page. It is off until you turn it on.
The status shows Running with the server’s address, for example 127.0.0.1:8080. AI apps connect to http://127.0.0.1:8080/mcp.

The port is 8080 unless you changed it. SoftGlaze AI shares one local server with the Developer API, so both use the same port. The Owner can change it on the Settings tab (any port from 1024 to 65535); after a change, update every connected AI app.

The page has seven tabs: Connect, Tokens, Approvals, Activity, Memory, Prompts and Settings. The Connect tab shows the setup for each AI app with your real port filled in, so you can copy it from there instead of from this page.

Create a token

Every AI app connects with its own token. Make one per app and per computer, so you can see what each one does and switch one off without touching the others.

Open the Tokens tab and press Create token, or press Create a token for this app on an app’s card in the Connect tab.
Fill in the form:
- Name: which app and which computer, for example “Claude Desktop on my PC”.
- Acts as: the team member the AI works as. It gets that member’s permissions and sees only the profiles that member may open. Everything it does is logged under that member.
- What it may do: the scope (see below). Read only is the default.
- Expires after: 7, 30 or 90 days, or never. A token that never expires stays valid until you revoke it.
- Profiles it may use: all the member’s profiles, or only some groups.
Press Create token and copy it. It starts sgai_ followed by 40 characters. SoftGlaze shows it only this once. It keeps only a SHA-256 hash, so a lost token can’t be recovered: revoke it and make a new one.

Create a token: table
Scope	What the AI app can do	Who can create it
Read only	Look at profiles, proxies, groups, macros, activity and the workspace memory. Check a proxy or a profile’s health. Change and start nothing.	Owner or Admin
Operate	Everything in Read only, plus create and change profiles, start and stop them, assign and rotate proxies, run macros and warm-ups, and work inside pages. Every change still asks you first.	Owner or Admin
Full	Everything in Operate, plus the one Expert tool when Expert mode is on. Only for apps you fully trust.	Owner only

A few rules the app enforces:

An Admin can make tokens only for themselves or for members they manage, never one that acts as the Owner.
An AI app sees only the tools its scope allows. A Read only token doesn’t even list the tools that change things.
If the member a token acts as is removed, suspended or banned, the token stops working.
Revoke on the Tokens tab cuts that app off at once: its connection closes and its pending requests are cancelled.

Connect an AI app

Each setup below is the one the app’s Connect tab gives you. For Claude there are also ready-made installs: the .mcpb extension for Claude Desktop chats and Cowork, and two plugins for Claude Code. Use one way per app. Replace two placeholders:

<PORT>: the port on the SoftGlaze AI page, 8080 unless you changed it.
<YOUR_TOKEN>: the token you just created.

Connect an AI app: table
AI app	How it connects	Where the setup goes
Claude Desktop	The .mcpb extension, or the SoftGlaze bridge (a local command)	Claude Desktop’s extension settings, or `claude_desktop_config.json`
Claude Code	The SoftGlaze plugins, or Streamable HTTP	`/plugin install`, or a terminal command
Cursor	Streamable HTTP	`~/.cursor/mcp.json`
VS Code (GitHub Copilot)	Streamable HTTP	`.vscode/mcp.json`
Gemini CLI	Streamable HTTP	`~/.gemini/settings.json`
ChatGPT desktop and Codex	Streamable HTTP	`~/.codex/config.toml`
Windsurf (Devin Desktop)	Streamable HTTP	`mcp_config.json`
Cline	Streamable HTTP	`cline_mcp_settings.json`
n8n	Server-Sent Events (SSE), or the local API	The MCP Client Tool node
Other apps	Streamable HTTP, SSE or the bridge	The app’s MCP settings

After you connect, check the connection.

Claude Desktop

The quickest way is the SoftGlaze extension for Claude Desktop: download softglaze-browser.mcpb, double-click it and paste your token when Claude Desktop asks. It works in Cowork too. See Install in Claude Desktop for the steps and the SHA-256. Use the extension or the setup below, not both.

To set it up by hand instead: Claude Desktop starts local MCP servers as programs, so it connects through the SoftGlaze bridge, a small script inside SoftGlaze that passes everything to the AI server. SoftGlaze runs the bridge with its own executable, so you don’t need Node.js.

Create a token for Claude Desktop.
In Claude Desktop, open Settings, then Developer, then Edit Config. This opens claude_desktop_config.json.
Paste the setup, with your token in place of <YOUR_TOKEN>. If the file already lists other servers, add "softglaze" inside the existing "mcpServers".
Quit Claude Desktop completely and open it again. SoftGlaze shows up under the + button below the chat box, in Connectors.

For a default installation:

{
  "mcpServers": {
    "softglaze": {
      "command": "C:\\Program Files\\SoftGlaze Browser\\SoftGlaze Browser.exe",
      "args": [
        "C:\\Program Files\\SoftGlaze Browser\\resources\\app.asar.unpacked\\src\\main\\ai\\bridge\\softglaze-mcp-bridge.js"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1",
        "SOFTGLAZE_MCP_URL": "http://127.0.0.1:<PORT>/mcp",
        "SOFTGLAZE_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

If you installed SoftGlaze in another folder, copy this setup from the Connect tab instead: it fills in the real paths.
ELECTRON_RUN_AS_NODE makes the SoftGlaze executable run the bridge script instead of opening a window. If you have Node.js 18 or newer, "command": "node" with the same args works too.
The one-click alternative is the softglaze-browser.mcpb extension above. If you switch to it, remove the "softglaze" entry from this file.

Claude Code

The SoftGlaze plugins add the skills and the tools in three commands: /plugin marketplace add softglazee/softglaze-claude-plugin, then /plugin install softglaze-browser@softglaze and /plugin install softglaze-browser-connector@softglaze. See Install in Claude Code. Or add the server yourself:

Create a token for Claude Code.
Run this in a terminal, with your token in place of <YOUR_TOKEN>:

claude mcp add --transport http softglaze http://127.0.0.1:<PORT>/mcp --header "Authorization: Bearer <YOUR_TOKEN>"

Start Claude Code and type /mcp. SoftGlaze should show as connected.

The command adds SoftGlaze to the current project only. Add --scope user to use it in every project.

Cursor

Create a token for Cursor.
Open ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project) and add:

{
  "mcpServers": {
    "softglaze": {
      "url": "http://127.0.0.1:<PORT>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

In Cursor’s settings, check that SoftGlaze is listed and switched on. Then ask the chat to list your SoftGlaze profiles.

To keep the token out of the file, put it in an environment variable named SOFTGLAZE_TOKEN and write "Bearer ${env:SOFTGLAZE_TOKEN}" as the header value.

VS Code (GitHub Copilot)

Create a token for VS Code.
Add this to .vscode/mcp.json in your workspace, or run MCP: Open User Configuration from the Command Palette to use it everywhere:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "softglaze-token",
      "description": "SoftGlaze AI token",
      "password": true
    }
  ],
  "servers": {
    "softglaze": {
      "type": "http",
      "url": "http://127.0.0.1:<PORT>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:softglaze-token}"
      }
    }
  }
}

The first time SoftGlaze starts, VS Code asks for the token and stores it securely, so it never sits in the file. Paste your token there.
Open Copilot Chat and ask it to list your SoftGlaze profiles. Allow the tool when VS Code asks.

Gemini CLI

Create a token for Gemini CLI.
Add softglaze inside "mcpServers" in ~/.gemini/settings.json:

{
  "mcpServers": {
    "softglaze": {
      "httpUrl": "http://127.0.0.1:<PORT>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Or let Gemini CLI write it for you:

gemini mcp add --transport http -s user --header "Authorization: Bearer <YOUR_TOKEN>" softglaze http://127.0.0.1:<PORT>/mcp

Start gemini and type /mcp. SoftGlaze and its tools should be listed.

Leave Gemini’s trust setting off. It only skips Gemini’s own confirmation; SoftGlaze asks you before every change anyway.

ChatGPT desktop and Codex

The ChatGPT desktop app, the Codex CLI and the Codex IDE extension share one configuration file, ~/.codex/config.toml. Codex reads the token from an environment variable, so the file never holds it.

Create a token for Codex.
Save it in an environment variable named SOFTGLAZE_TOKEN. On Windows, run this once in Command Prompt or PowerShell, then open a new terminal:

setx SOFTGLAZE_TOKEN "<YOUR_TOKEN>"

Add this to ~/.codex/config.toml:

[mcp_servers.softglaze]
url = "http://127.0.0.1:<PORT>/mcp"
bearer_token_env_var = "SOFTGLAZE_TOKEN"
tool_timeout_sec = 120

Restart the app, or open a new terminal and start Codex, then type /mcp. SoftGlaze should be listed.

tool_timeout_sec = 120 gives a tool call two minutes instead of Codex’s default 60 seconds, which matters while SoftGlaze waits for your answer to an approval.

Windsurf (Devin Desktop)

Windsurf is now called Devin Desktop, and the two keep their MCP settings in different files.

Windsurf: add this to ~/.codeium/windsurf/mcp_config.json, then refresh the MCP servers and check that SoftGlaze is listed.

{
  "mcpServers": {
    "softglaze": {
      "serverUrl": "http://127.0.0.1:<PORT>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Devin Desktop: its user settings are in ~/.config/devin/mcp_config.json (Devin’s own docs give %APPDATA%\devin\mcp_config.json on Windows), and a remote server uses url with "transport": "http" instead of serverUrl:

{
  "mcpServers": {
    "softglaze": {
      "url": "http://127.0.0.1:<PORT>/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Cline

Create a token for Cline.
In the Cline panel, open MCP Servers, then the Configure tab, then Configure MCP Servers. This opens cline_mcp_settings.json.
Add:

{
  "mcpServers": {
    "softglaze": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:<PORT>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Check that SoftGlaze shows as connected in Cline’s MCP Servers list.

Keep "type": "streamableHttp": without it, Cline assumes the older SSE transport. Leave autoApprove empty; SoftGlaze asks you before every change.

n8n

n8n has to run on the same computer as SoftGlaze (with npx n8n or in Docker). n8n Cloud can’t reach your computer yet. There are two ways in, and you can use both in one workflow.

A. Let an n8n AI Agent use SoftGlaze

Add an AI Agent node, then add an MCP Client Tool node as one of its tools.
Set SSE Endpoint to http://127.0.0.1:<PORT>/mcp/sse. If your n8n version asks for a Server Transport instead, either works: Server-Sent Events with the /mcp/sse address, or HTTP Streamable with http://127.0.0.1:<PORT>/mcp.
Set Authentication to Bearer and create a Bearer credential with your token.
Under Tools to Include, pick All, or Selected with only the tools the workflow needs.

B. Fixed steps with the HTTP Request node

A step that never changes, such as “start profile 42 at 9:00”, doesn’t need an AI agent. An HTTP Request node can call any SoftGlaze tool through the local API:

Method: POST
URL: http://127.0.0.1:<PORT>/api/v1/tools/start_profile
Authentication: Generic Credential Type, then Bearer Auth, with your token.
Body: JSON, the tool’s arguments, for example { "id": 42 }.
Options, Timeout: 130000. n8n gives up after 10 seconds by default, and a call that needs your approval can wait up to 2 minutes.

Unattended workflows

A workflow that runs on a schedule has nobody to press Allow. Give it an automation token: it pre-approves only the tools you pick, only for the groups you pick, with limits per call and per hour. Read-only tools don’t ask by default, so a report workflow can use a Read only token.

n8n in Docker

Use host.docker.internal instead of 127.0.0.1, for example http://host.docker.internal:<PORT>/mcp/sse.
On the SoftGlaze AI Settings tab, add host.docker.internal under Extra allowed host names (Owner only). Without it, SoftGlaze refuses the request with “Invalid Host header”.

The server still listens on 127.0.0.1 only. Whether Docker Desktop can reach a server bound to 127.0.0.1 on Windows is not verified yet. If the connection fails, run n8n outside Docker with npx n8n. Docker Engine on Linux won’t reach it at all; run n8n outside Docker or with host networking.

Workflow templates (Beta, check before use)

Four workflows you can import into n8n with Import from File, or with Import from URL and the link. They use the HTTP Request node and the local API, so they need no AI agent. They are Beta and have not been run against a live SoftGlaze yet: check each node before you turn a workflow on. Each one marks what you fill in with CHANGE_ME.

Daily health report to Telegram or Slack: every morning, reads the workspace summary, running profiles, failing proxies and the pool’s health, and sends a short report. Read only token. The Slack node is switched off; switch on the one you want.
Create profiles from a Google Sheet: reads rows (name, group, proxyId, startUrl, notes, tags) and calls create_profile for each, one per second. Automation token with create_profile pre-approved for the target groups.
Scheduled warm-up: every day, picks stopped profiles in one group and starts the Cookie Warmer on up to 5 of them, one at a time. Automation token with start_warmer pre-approved for that group.
Telegram “/start profile” command: send /start US-ADS-01 to your Telegram bot and it starts that profile and replies. It answers only your own chat id. Automation token with start_profile pre-approved.

Other apps

Any MCP client that supports Streamable HTTP with headers can connect:

{
  "name": "softglaze",
  "transport": "streamable-http",
  "url": "http://127.0.0.1:<PORT>/mcp",
  "sseUrl": "http://127.0.0.1:<PORT>/mcp/sse",
  "headers": {
    "Authorization": "Bearer <YOUR_TOKEN>"
  }
}

Clients that only speak the older HTTP+SSE transport use the SSE address, http://127.0.0.1:<PORT>/mcp/sse.
Clients that can only start a local program (stdio) use the SoftGlaze bridge: the same command, arguments and environment as for Claude Desktop.
Send the token in an Authorization header: Bearer, a space, then the token.

Check the connection

Ask your AI app: “Read the SoftGlaze workspace summary.” It should call workspace_summary and tell you how many profiles, groups and proxies it can see, which plan you are on and what its token may do. Read-only tools don’t ask you, so this works straight away.

Then look at the SoftGlaze AI page: the status line shows the app under Connected apps, and the Activity tab lists the call.

If it doesn’t work, see troubleshooting.

Approvals

SoftGlaze decides what needs your OK, inside SoftGlaze, whatever the AI app’s own settings say. When an AI app wants to change something, a dialog opens on any page of the app, and the request is listed on the Approvals tab:

It names the app, the token, the member it acts as, and what it wants to do, with the profiles it would touch. Show details lists the arguments, with passwords and other secrets hidden.
Allow once runs this one request.
Allow for 1 hour also lets the same kind of request from the same token run without asking for the next hour.
Deny refuses it. The AI app is told not to retry.
No answer in 2 minutes counts as Deny.

The Owner, Admins and the member a token acts as can answer its requests.

Approvals: table
What the AI app asks for	When SoftGlaze asks you
Read-only tools: listing, reading, checking health	Never, by default
Tools that change something	Asks you. By default the dialog offers Allow for 1 hour, which lets that tool run for the same token without asking for an hour
A macro run or warm-up on more than one profile, or stopping all profiles	Every time; Allow for 1 hour isn’t offered
Page tools inside a running profile	Once per profile: Allow for 1 hour covers every page tool on that profile for an hour
Stopping a profile or a run that the same token started	Never
The Expert tool (handing a profile to Playwright or Puppeteer)	Every time
Pre-approved tools on an automation token, within its limits	Never; logged as Pre-approved

On the Settings tab, under When SoftGlaze asks you, choose per scope: Never ask (read-only tools only), Ask once an hour or Ask every time. Changing tools can’t be set to Never ask.

When the AI app is waiting

Most AI apps give up on a tool call after 60 seconds. SoftGlaze holds a call for up to 50 seconds while it waits for you. If you haven’t answered by then, the AI app gets this message: waiting for the user to approve in the SoftGlaze app, call again with exactly the same arguments. A well-behaved AI app tells you and calls again. When you press Allow, the repeated call runs once. If you answer after the AI app stopped waiting, your Allow is kept for that identical call for two minutes.

Some tools take longer than an AI app waits: creating many profiles and finding free proxies. After 40 seconds they carry on in the background and hand back a run id that starts job-. The AI app follows it with get_run_status. Macro runs and warm-ups always return a run id (par- and warm-) straight away.

Stop all AI

Use Stop all AI at the top of the SoftGlaze AI page if an AI app does something you didn’t expect. You can also type “Stop all AI” in the command palette, which opens the same confirmation. It:

stops every run and every profile an AI app started;
disconnects every connected AI app and cancels calls in progress;
denies every request waiting for your answer, and forgets every Allow for 1 hour;
switches SoftGlaze AI off. Tokens stay valid; switch AI server on again when you are ready.

To cut off one app only, revoke its token on the Tokens tab.

Activity

The Activity tab lists everything AI apps did through SoftGlaze: the time, the app and token, the tool, what happened, the result (OK, Denied, Error or Waiting), how it was approved, and how long it took. Filter by result or app, or search. Arguments are stored with secrets hidden.

Memories

Memories are notes an AI app reads before it acts. SoftGlaze offers three, as MCP resources, and its server instructions tell every AI app to read them first:

Workspace memory (softglaze://memory/workspace): your own rules, in Markdown, up to 20 KB. Edit it on the Memory tab (Ctrl+S saves). It starts as a template with sections for what the workspace is for, naming, what each group is for, proxy rules, working hours and pacing, and a never-do list. Replace the examples with your own rules and keep it short: AI apps read all of it every time.
How SoftGlaze works (softglaze://guide/how-softglaze-works): built in and read-only. Profiles, fingerprints, proxies, sessions, macros, page tools, plan limits, approvals, and how to use the tools well.
Acceptable use (softglaze://guide/acceptable-use): built in and read-only. What SoftGlaze may and may not be used for. AI apps are told to refuse anything it prohibits and to say why.

Two more resources are live and read-only: softglaze://workspace/summary and softglaze://profiles/{id}.

An AI app can read the memory with read_memory and add to it with update_memory, which asks you first. Reset to default on the Memory tab puts the template back.

Some apps load resources on their own; others only when you ask. If your app doesn’t seem to follow your rules, tell it: “Read the SoftGlaze workspace memory first.”

Prompts

SoftGlaze comes with 12 ready-made prompts, from a daily health check to a weekly report. They are MCP prompts, so apps that support prompts list them, and the same list is on the Prompts tab and in the prompt library:

Claude Code: type / and pick a softglaze prompt, or type /mcp__softglaze__daily_health_check.
Claude Desktop: click + below the chat box and look for SoftGlaze.
VS Code: type / in Copilot Chat and pick a SoftGlaze prompt.
Cursor and other apps: if prompts aren’t listed, copy the prompt text from the library, paste it into the chat and fill in the details.

Automation tokens

An automation token is for workflows that run without you: n8n, schedules and scripts. It is an Operate token with a short list of tools that run without asking. Only the Owner can create one.

On the Tokens tab, press Create token and choose Operate.
Under Profiles it may use, tick the groups the workflow may touch. An automation token must be limited to groups.
Open Automation token (for n8n, schedules and scripts) and tick the tools that may run without asking.
Set the limits:
- Most profiles per call: default 5, from 1 to 50.
- Most calls per hour: default 60, from 1 to 1000.

Pre-approved calls skip the dialog, are logged as Pre-approved, stay inside the chosen groups, obey your plan’s limits and stop with Stop all AI. A call over a limit, or any tool you didn’t tick, asks you as usual. The Expert tool can never be pre-approved.

Local API

AI tokens also work on the local REST API while SoftGlaze AI is on. That is what the n8n HTTP Request node and your own scripts use.

Local API: table
Request	What it does
`GET /api/v1/tools`	Lists the tools this token may use, with scope and approval rule
`POST /api/v1/tools/<tool>`	Runs a tool; the JSON body is its arguments
`GET /api/v1/profiles`	Lists profiles (`page`, `pageSize`, `group`, `search`, `status`, `tag`)
`GET /api/v1/sessions`	Lists running profiles
`POST /api/v1/profiles/<id>/start`	Starts a profile (`url`, `headless`)
`POST /api/v1/profiles/<id>/stop`	Stops a profile
`GET /api/v1/health`	Status check, no token needed

curl -X POST http://127.0.0.1:<PORT>/api/v1/tools/list_proxies -H "Authorization: Bearer <YOUR_TOKEN>" -H "Content-Type: application/json" -d "{\"status\":\"fail\"}"

A successful call answers { "ok": true, "summary": "...", "data": { ... } }.

Every call goes through the same checks as MCP: scope, the member’s permissions, groups, approvals, plan limits and the activity log.
A REST call that needs approval waits for your answer, up to 2 minutes, then gets its result (or 403 if you deny it). Give your HTTP client a timeout longer than that.
Developer API keys (sg_, from Settings, Developer API Access) also work here. They are for your own scripts, which can’t answer a dialog, so they don’t ask. They can’t connect to /mcp.

Answers you may see: 200 OK; 202 still waiting for approval; 400 bad arguments; 401 no valid token; 403 refused; 404 unknown tool; 413 body too large; 423 the workspace is locked; 429 too many calls; 503 SoftGlaze AI is switched off.

Settings

The Settings tab on the SoftGlaze AI page:

When SoftGlaze asks you: the approval mode for read, operate and full tools.
Sites the AI may work on: page tools work only on these sites and their subdomains, up to 200. Empty means any site, and you are still asked first.
Extra allowed host names (Owner only): host names the server answers to besides 127.0.0.1, for example host.docker.internal. Up to 10, no wildcards. The server still listens on 127.0.0.1 only.
Expert mode (Owner only, off by default): lets a Full token ask to hand a running profile to Playwright, Puppeteer or Chrome DevTools. Websites can detect an outside debugger, so profiles may be flagged or blocked. Every hand-off asks you. How to attach Playwright MCP or Chrome DevTools MCP: Use SoftGlaze with Playwright MCP and Chrome DevTools MCP.
Server port (Owner only): 1024 to 65535.

Troubleshooting

The AI server won’t start: the port is in use

“Port 8080 is already in use by another program.” Another program holds the port. Close it, or let the Owner pick another port on the Settings tab, then update the address in every AI app.

401: the token is missing, wrong, revoked or expired

The app sent no Authorization: Bearer header, or a token SoftGlaze doesn’t know. Check that the whole token was pasted, with no space or line break, and that it wasn’t revoked or expired on the Tokens tab. Tokens can’t be shown again: create a new one. After 30 failed sign-ins within a minute, SoftGlaze answers every sign-in with 429 until the minute has passed.

403: the request was refused

Invalid Host header: the request was addressed to a name other than 127.0.0.1, localhost or [::1]. For Docker, add host.docker.internal to Extra allowed host names.
Requests from web pages are not allowed: a browser page tried to call the server. Only apps on your computer can.
This token is a Developer API token: keys that start sg_ don’t work on /mcp. Create a SoftGlaze AI token.
The member this token acts as no longer exists, or is suspended: create a new token for an active member.
This token has the read scope: the tool needs Operate (or Full). Create a token with that scope.
Outside the groups this token may use: the token is limited to some groups.

423: the workspace is locked

SoftGlaze is waiting for the workspace password. Unlock it in the app, then try again.

503: SoftGlaze AI is switched off

Switch AI server on again. Stop all AI switches it off on purpose.

The AI app says it is waiting for approval

Look for the dialog in SoftGlaze, or open the Approvals tab. The AI app should call the tool again after you answer; if it doesn’t, ask it to. In Codex, keep tool_timeout_sec = 120.

“No one answered the approval within 2 minutes”

The request timed out and was denied. Ask the AI app to try again while you are at the computer, or give an unattended workflow an automation token.

The connection drops after SoftGlaze restarts

Sessions don’t survive a restart, a Stop all AI or switching the server off. Reconnect SoftGlaze in your AI app (for example /mcp in Claude Code, or restart Claude Desktop). An AI session left idle for 30 minutes is closed too.

“Too many calls from this token”

One token may make 120 calls a minute. Wait a moment. An automation token that goes over its calls per hour falls back to asking you.

A tool is missing

The app lists only the tools the token’s scope allows. Page tools work on Chromium profiles only. The Expert tool appears only with Expert mode on and a Full token that acts as the Owner.

Page tools refuse to work

The profile has to be running (start it with start_profile), it has to be a Chromium profile, and the site has to be on the “Sites the AI may work on” list if that list isn’t empty.

Claude Desktop shows SoftGlaze as failed

With the .mcpb extension: check the token and port in the extension’s settings (Settings, Extensions in Claude Desktop).
Check that SoftGlaze is open and AI server is on.
Check the two paths in the config against your installation; the Connect tab shows the right ones.
Check SOFTGLAZE_TOKEN and the port in SOFTGLAZE_MCP_URL.
Claude Desktop’s MCP log shows the bridge’s messages, such as “SoftGlaze is not reachable” (the app or the server is off) or “SOFTGLAZE_TOKEN is not set”.

n8n in Docker can’t connect

Add host.docker.internal to Extra allowed host names and use it in the address. If it still fails, run n8n outside Docker with npx n8n (see n8n in Docker).

Security tips

One token per app and per computer. Name it so you recognise it.
Start with Read only. Move to Operate when you want the AI to change things. Keep Full for apps you fully trust.
Let tokens expire. 30 days is a good default. Revoke the ones you no longer use.
Limit tokens to groups when the AI only needs some profiles.
Keep tokens out of files you share. Use VS Code’s prompt, Codex’s environment variable or Cursor’s ${env:...}, and never paste a token into a chat.
Read before you press Allow. The dialog names the profiles; Show details shows the arguments.
Keep Expert mode off unless you need it.
Use the site list for page tools when the AI should work on a few sites only.
Treat page text as untrusted. A web page can contain text written to trick an AI. SoftGlaze marks page text as untrusted and tells AI apps not to follow instructions in it, but review what the AI proposes.
Know where your data goes. SoftGlaze AI sends nothing to SoftGlaze. Your AI app sends what it reads (profile names, proxy countries, page text) to its own AI provider, under that provider’s terms.
Some things are never available to AI apps: cookies, 2FA codes, proxy usernames and passwords, saved-login and Data Vault passwords, deleting or purging anything, billing, member and role changes, settings that weaken security, and running arbitrary JavaScript in pages. The tool reference has the list.

Limits of the Beta

Beta. Tools, prompts and setups may change before the full release.
Local only. Web-only AI apps and n8n Cloud need the Cloud Relay, which comes later.
Sites can notice automation. Page tools type and click like a person, through the profile’s own proxy and fingerprint, over SoftGlaze’s existing connection to the browser. Like any automation, some sites can still detect it. SoftGlaze makes profiles harder to link, not impossible.
AI apps make mistakes. Approvals are there so you can catch them. Read each request.
Plan limits apply. A macro run handles up to 3 profiles at once on Pro and 10 on Enterprise and during the trial, whatever the AI asks for.
Acceptable use applies. The acceptable use policy covers everything an AI app does through SoftGlaze.