Skip to main content
Claude Cowork and Claude Code in the cloud run on Anthropic machines, not on devices your MDM manages, so the MDM rollout cannot reach them. The Lumos plugin carries the same hook into those sessions, and into every other Claude Code and Cowork session it loads in. You build the plugin once for your organization and upload it to claude.ai, and Lumos checks the tool calls of every member who gets it.

​
What the plugin does

The plugin holds your organization’s plugin secret. At the first tool call of each Claude session, it trades that secret for a short-lived session token, and Lumos checks every tool call in the session with that token, the same way it checks calls from an enrolled device. Tool calls appear under MCP Governance → Events with the member’s email, and your policies apply to them. The plugin governs every Claude Code and Cowork session it loads in, whatever app or environment started it. See Rolling out alongside MDM.
This is a best-effort control, not a hard boundary. In a cloud session, the agent runs as root on its machine, so it can read the secret and skip the hook. A tool call whose hook did not run never reaches Lumos, and neither your policies nor the organization list applies to it. The email comes from the Claude session and nothing signs it, so someone who holds the secret can start a session under another member’s email. When a session reports an email your directory does not know, the Claude plugin’s row on the Deployment tab shows Unknown email.
If Lumos cannot be reached or is slow to answer (each request waits at most 4 seconds, and the hook spends at most 8 seconds in all), the tool call runs unchecked. A refusal from Lumos blocks the call; see When a tool call is blocked.
Every member of your Claude organization can read the plugin’s files, including the secret. Lumos refuses a session whose Claude organization is not on the list you keep on the MCP Governance Deployment tab. The plugin reads that organization ID from the Claude session, so the list catches a secret copied into another organization; it does not stop someone who also copies one of your organization IDs.

​
Rolling out alongside MDM

The plugin and the MDM rollout are separate. You can use either one, or both. What the plugin checks. The plugin checks every Claude Code and Cowork session it loads in, whatever app or environment started it:
  • Cowork in the cloud, and Cowork on the member’s computer.
  • Claude Code on the web (claude.ai/code), and Claude Code cloud sessions started from the Claude desktop app.
  • Claude Code on the member’s computer, in the Claude desktop app or in a terminal.
What the MDM rollout checks. The MDM rollout checks Claude sessions that run on a managed computer. Claude Code in a terminal. A terminal session gives the plugin no email. On a computer without a Lumos device token, the plugin blocks its tool calls with reason email_missing until the computer is enrolled with Lumos. Tell members who use Claude Code in a terminal before you publish the plugin.
When both run. On a computer with the MDM rollout, both hooks check each tool call of a local session, for example Claude Code in a terminal or in a Local session of the Claude desktop app. The plugin then uses the computer’s device token, so both checks use the same identity: the second check reuses the first one’s verdict, and the call appears twice in MCP Governance → Events.
The plugin sends the session’s entrypoint to Lumos as a label. Lumos records it and decides nothing on it, so a Claude app or environment added later is checked like any other.
The plugin loads only when the member signs in with their claude.ai account.The plugin does not cover Claude in Slack. If you add the plugin to a Claude in Slack bundle, its tool calls run without a check, and Lumos does not record them.

​
Set up, rotate and roll back

​
Set up

You need Organization Admin in Lumos, with MCP Governance enabled on your domain, and permission to upload plugins in your claude.ai organization. In Lumos, go to MCP Governance → Deployment, open Claude plugin, and go to the First-Time Setup tab. It shows the same three steps. A step that Lumos can confirm shows a check mark.
Lumos turns the Claude plugin on for your organization. If Claude plugin is not listed on the Deployment tab, contact your Lumos team.
1

Create the secret and build the plugin

Click Create the secret, and give it a name and a lifetime under Expires in (90 days by default). Lumos shows the secret once. In the same window, click Download plugin zip.
Your browser fetches the plugin files from Lumos, checks the secret, and saves your organization’s plugin zip. The secret goes only into that zip, and the build takes no Claude organization ID. You build once for everyone.
Creating your organization’s first secret turns on governance for the plugin. You can also create a secret later with Create secret on the Plugin secrets card of the Status tab.
If someone in your organization turned governance off for the Claude plugin earlier, creating a secret does not turn it back on. While it is off, Lumos refuses every plugin session, so every governed tool call is blocked, and the Claude plugin’s row on the Deployment tab says Governance off. Ask Lumos support to turn it back on.
2

Add your Claude organization ID

In claude.ai, Settings › Account shows your Organization ID. In Lumos, click Add organization and paste it. Add every Claude organization that will run the plugin. Do this step before you test the plugin in step 3.
While the list is empty, Lumos refuses every plugin session, so every tool call in a plugin session is blocked. Lumos does not accept an ID that is already on the list.
3

Upload it to Claude

In claude.ai, go to Organization settings › Plugins & skills and upload the zip. Make it Available to install for a test group. As a test-group member, install the plugin. If you test with Claude Code, first allow Lumos in your cloud environment, as in Allow Lumos in Claude Code cloud environments. Then start a new Cowork or Claude Code session, for example Cowork in the cloud or Claude Code on the web (claude.ai/code), and use any tool, for example by asking it to list the files in its folder.In Lumos, open the Claude plugin’s Status tab to check the session:
  • The first line counts the members with a session, for example 1 person has a governed Claude session now.
  • Click View in Events. MCP Governance → Events opens, filtered by Claude plugin secret to show only the plugin’s tool calls.
  • Your tool call shows your email in the User column. The Harness column shows Claude Cowork for a Cowork session and Claude Code for a Claude Code session.
Then make the plugin Required. In claude.ai, go to Organization settings › Plugins & skills, open the lumos-mcp-governance plugin, and set Install to Required. Members get it at their next session start.
  • Your Claude organization is listed on the Claude organizations card.
  • The Advanced card shows a First plugin session received callout the first time you open it. On the First-Time Setup tab, this step gets a check mark.
A session loads plugins when it starts, so a session that was already open does not have the plugin.
If the session’s tool calls are blocked with reason client_org_mismatch, step 2 was skipped. Add your organization ID as in step 2, and then start a new session.

​
Allow Lumos in Claude Code cloud environments

Which environments need it. Every cloud environment that members of your Claude organization use for Claude Code, including the Default environment. In a self-hosted environment, allow the domain at your own network boundary instead.
Claude Code cloud sessions run in a cloud environment, whether they start on the web, from the Claude desktop app, from the Claude mobile app, or with claude --cloud in a terminal. Each environment limits the domains its sessions can reach, and its default network access level, Trusted, does not include Lumos. In an environment that does not allow mcp-governance.lumos.com, the plugin cannot reach Lumos. Tool calls then run unchecked, Lumos does not record them, and the member sees no warning.
Each environment has its own list of allowed domains. Claude has no organization-wide list that adds a domain to every environment.
Where the setting is. Anthropic describes the setting in Network access.
  • A shared environment: an Owner of your claude.ai organization edits it on the Cloud environments page in claude.ai admin settings.
  • A member’s own environment: only that member can edit it. At claude.ai/code, open the environment selector under the message box, find the environment under Cloud, and click the settings icon on its row. In a running session, click the caret after the session title and choose Edit cloud environment.
In the environment’s dialog, look at Network access, and change only what adds the domain:
  • Trusted (the default): set it to Custom. In Allowed domains, add mcp-governance.lumos.com on its own line. Check Also include default list of common package managers, so that sessions can still reach the domains that Trusted allows.
  • Custom: add mcp-governance.lumos.com on its own line in Allowed domains. Leave the checkbox as it is.
  • Full: change nothing. Sessions can already reach Lumos.
  • None: set it to Custom, add mcp-governance.lumos.com in Allowed domains, and leave the checkbox unchecked. Sessions then reach Lumos and no other domain through the session’s network.
Save the environment.
To cover members who do not edit their own environments, an Owner can create a shared environment that allows the domain and make it the organization’s default environment at claude.ai/admin-settings/claude-code. A member who chooses one of their own environments still needs the domain in that environment.
For members’ own environments, this is a best-effort control. An Owner controls shared environments, including the organization’s default, but each member controls their own. A member who runs Claude Code in an environment without the domain runs those tool calls unchecked. Set a shared environment that allows the domain as the organization’s default, and rely on Lumos’s governance of each app’s entitlements as the backstop.
Check that it works. Start a new Claude Code session in the environment and ask Claude to run this command:
It prints 200. If it prints 403 or 000, or prints nothing, the environment still blocks Lumos. Then run one tool call and check that MCP Governance → Events shows it with your email.
Lumos cannot detect an environment that blocks it: no call reaches Lumos, so nothing is recorded and no alert fires.
Run the check again after you create or change an environment. From time to time, check that MCP Governance → Events shows Claude Code calls from the members you expect.

​
The Claude organization list

You manage the list on the Claude organizations card of the Status tab. Adding or removing an organization applies to new sessions within a minute.
The list belongs to your Lumos organization, not to a secret. Every live plugin secret works for every Claude organization on the list, and the build takes no organization ID. A session that already has a token keeps working until the plugin next renews its token, within the session length (60 minutes by default).

​
When the build fails

If the build fails, the window says Lumos could not build the plugin zip and gives the reason. Click Try again while the window is open. If you close the window first, the secret is gone: rotate it, as in Rotate the secret, and download the zip from the rotate window.
The browser checks the secret’s format and expiry before it saves the zip. It does not verify the signature; the test-group session in step 3 catches a damaged secret.

​
Rotate the secret

Rotate the secret before it expires, or if it may have leaked: for example, if the plugin zip or the secret reached someone outside your Claude organization, or if members are blocked with issuance_ceiling and you do not expect that many sessions. A secret lasts 7 days, 30 days, 90 days or 1 year, as you chose under Expires in. From 14 days before it expires, its row on the Plugin secrets card shows Expiring, and the Claude plugin’s row on the Deployment tab flags Secret expiring.
  1. Open the Claude plugin’s Update Plugin tab and click Rotate secret. Lumos shows the new secret once. In the same window, click Download plugin zip to build the new plugin zip.
  2. In claude.ai, replace the plugin with the new zip and keep it Required, as in step 3. The Update Plugin tab shows the date by which to do it.
Ask members to start a new session before the grace period ends.
The old secret keeps working for the grace period (7 days by default) or until it expires, whichever comes first. The rotate dialog shows the date. The organization list does not change. You can also rotate a secret from its row on the Plugin secrets card of the Status tab.
A Claude session loads the new plugin at its next start. A session that is already running keeps the old secret until it restarts. While members still have sessions on the old secret, the Claude plugin’s row on the Deployment tab shows Secret rotating. Once the old secret stops working, their tool calls are blocked until they start a new session.

​
Roll back

Roll back when a plugin build you uploaded breaks members’ sessions and you want the previous build back. Rolling back changes which plugin build members run. Unlike rotating, it makes no new secret, and unlike turning the plugin off, it keeps Lumos checking tool calls. Upload the previous zip if its secret is still live (check the Plugin secrets card). Or revert to it in claude.ai: open the plugin’s page, go to Version history, open the menu of the previous version, select Revert to this version, and confirm. Do not revoke every plugin secret to roll back. Once no secret is live, Lumos refuses new plugin sessions, and their tool calls are blocked.
The same check on its secret applies. Either takes effect at each session’s next start. To remove the plugin from every member instead, see Turn the plugin off for everyone.

​
Turn the plugin off for everyone

If the plugin causes significant problems during deployment, an Owner of your claude.ai organization can remove it from every member’s environment. You do not need Lumos for this.
  1. In claude.ai, go to Organization settings › Plugins & skills.
  2. Open the lumos-mcp-governance plugin.
  3. Set Install to Not available. Anthropic’s help page calls this setting Default access.
On an Enterprise plan, a user group with its own setting for the plugin keeps that setting. Set each such group to Not available too. To turn the plugin back on, set Install back to the setting it had before. For most organizations that is Required.
claude.ai describes Not available as “Hidden from the plugin marketplace. Users won’t see or be able to install it.” Sessions without the plugin send no tool calls to Lumos, so Lumos does not check or record them. On a computer with the MDM rollout, the MDM hook still checks Cowork and Claude Code sessions that run on that computer. See Rolling out alongside MDM.

​
When a tool call is blocked

When Lumos refuses the plugin’s request, the member sees this message in place of the tool call’s result:
The member sees it as one line. A block by one of your policies is different: it names the policy, as for every other client. The <message> depends on the reason code. After you fix the cause, a blocked member starts a new Claude session. When you contact Lumos support about a block, include the reason code, the member’s email, your Claude organization ID and the time of the session.
After a refused sign-in, the plugin waits 5 minutes before it asks Lumos again in that session, and until then each tool call shows the same message. The current session asks Lumos again after up to 5 minutes, and a change in Lumos can take up to a minute to apply.
When a session token expires mid-session, the plugin renews it once and retries. If the renewal is refused, the member sees the reauth message with the refusal’s own reason code.
Any other reason code shows a message that depends on the kind of refusal: “Lumos refused the plugin’s credentials. Ask your admin”, “Lumos refused this request. Ask your admin”, “Lumos rate limit reached”, or “Lumos could not read the plugin’s sign-in request. Ask your admin for an updated plugin”. Contact Lumos support.

​
When tool calls run unchecked

The plugin lets a tool call run without a check when Lumos cannot be reached or is slow to answer (each request waits at most 4 seconds, and the hook spends at most 8 seconds in all), when Lumos answers with a server error or its service-wide limit, when the answer did not come from Lumos (such as a block from a proxy or firewall), and when curl is missing.
A Claude Code cloud environment that does not allow Lumos is one such case. See Allow Lumos in Claude Code cloud environments.
Claude Code also stops any hook run after 10 seconds. The plugin’s 8-second cap keeps a run inside that limit, so this happens only when the member’s machine or session stalls. If it does, Claude Code 2.1.295 and later block the call, and earlier versions let it run. The member’s Claude Code version decides this; in the cloud, Anthropic sets the version.