Agent connections
Connect from Lumo, or authorize from Lumo Userscripts — the same contract in both directions.
On this page
Lumo Userscripts can expose its scripts to an MCP client. The host in practice is Lumo, but the contract does not care who connects: any extension that can probe, be authorized, and open a runtime port gets the same tool surface.
Two directions, one contract#
There are two ways to start, and both end at the same session. Lumo can discover the provider; the provider can also treat an unknown caller as a request that needs a decision.
| Starting point | What happens | Where the user decides |
|---|---|---|
| From Lumo | Add the provider's 32-character extension ID under Settings → MCP → Extensions. | In Lumo, before the first probe. |
| From Lumo Userscripts | The provider answers the probe with authorized: false and queues a request. | In the provider's Settings → Agent, or in the approval dialog. |
| Either way | After approval, Lumo opens the lumo:mcp port and lists tools. | No further prompt unless the policy changes. |
Connect from Lumo#
- 1
Open MCP settings
Settings → MCP → Extensions. The same panel shows Lumo's own extension ID; approval needs it.
- 2
Add the provider ID
Paste the 32-character ID of Lumo Userscripts. IDs use only the letters a–p.
- 3
Let the probe run
Lumo sends one L0 probe. A disabled endpoint, missing authorization or an unavailable runtime is reported as a specific state, not a failed handshake.
- 4
Approve and connect
If the provider asks for approval, open its settings and allow Lumo's ID. Focus Lumo again; it retries the probe and opens the MCP session.
The ID is not the name
A provider's name is self-reported and only used for display. Authorization always compares sender.id, because a name can claim to be anything.
Authorize from Lumo Userscripts#
- 1
Turn on the endpoint
Settings → Agent → Agent access. It is off by default and nothing is discoverable while it is off.
- 2
Decide on writes
Allow writes is a second switch. Leave it off to expose only
list,getanddiagnostics. - 3
Add the caller
Paste Lumo's extension ID into Allowed extensions. The panel offers a copy button for the provider's own ID.
- 4
Review the queue
A pending request appears in the same section and in an interrupt dialog. Approve, dismiss, or defer for the session.
What the user sees when it is not ready#
| Provider state | Lumo shows | Fix |
|---|---|---|
| Not installed / no endpoint | Extension is not installed, or it does not expose an agent endpoint. | Check the ID, then reinstall or rebuild. |
| Endpoint off | Agent access is turned off in <name>. | Enable Agent access in the provider. |
| Not authorized | <name> does not allow this extension. | Add Lumo's ID to the provider's allowlist. |
| Approval pending | <name> is waiting for you to approve this extension. | Open the provider's settings and approve. |
| Not ready | The provider's own reason message. | Read the reason; usually chrome.userScripts is unavailable. |
Writing safely#
- Read tools are available once the endpoint is on and the caller is authorized.
- Write tools additionally require Allow writes; turning it off invalidates the next call, not the next session.
- Review mode creates new scripts disabled and marked pending review.
- Every write is rate-limited to 30 calls per minute and recorded in the activity list; parameters are hashed, not stored.
The agent is not a separate permission system
A script the agent creates runs with the same @match and @grant reach as one you write by hand. Review mode exists so a new script cannot run before you have seen it.
Troubleshooting#
| Symptom | Likely cause | Action |
|---|---|---|
| Tools disappear after a while | MV3 recycled the service worker; the port closed. | Call a tool again; Lumo reconnects and re-initializes lazily. |
| Tools exist but every write fails | Allow writes is off, or the rate window is exhausted. | Enable writes or wait a minute. |
| Approval prompt repeats | The caller's ID is not on the allowlist. | Add it under Settings → Agent → Allowed extensions. |
authorized: true but no tools | chrome.userScripts is unavailable or no scripts are installed. | Run diagnostics, then check Allow User Scripts. |
| Wrong extension connected | A 32-character ID was pasted incorrectly. | Copy the ID from the provider's agent section instead of typing it. |
For the wire format, state matrix and limits, read the extension-provider protocol. For the loop that consumes these tools, read the agent loop.