> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Governance for the Claude plugin

> Govern Claude Cowork and Claude Code tool calls with a Lumos plugin that your Claude organization requires for its members.

Claude Cowork and Claude Code in the cloud run on Anthropic machines, not on devices your MDM manages, so the [MDM rollout](https://docs.lumos.com/docs/mcp-governance-rollout.md) 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](#rolling-out-alongside-mdm).

> [!WARNING]
>
> **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](#when-a-tool-call-is-blocked).

> **Who can read the secret, and what the organization list catches**
>
> 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](https://docs.lumos.com/docs/mcp-governance-rollout.md) 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](https://code.claude.com/docs/en/desktop#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 the plugin and the MDM hook both run**
>
> **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](https://code.claude.com/docs/en/desktop#local-sessions) 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**.

> **How Lumos uses the session's entrypoint**
>
> 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.

> **Where the plugin does not load**
>
> 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.

> **If Claude plugin is not on the Deployment tab**
>
> 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**.

> **What the build does**
>
> 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.

> **What the first secret turns on, and creating a secret later**
>
> 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 governance was turned off earlier**
>
> 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.

> **Why the organization ID matters**
>
> 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 Cowork, first allow Lumos for Cowork, as in [Allow Lumos in Cowork](#allow-lumos-in-cowork). If you test with Claude Code, first allow Lumos in your cloud environment, as in [Allow Lumos in Claude Code cloud environments](#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.

> **Other signs on the Status tab that the session worked**
>
> * 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.

> **If the session does not have the plugin**
>
> A session loads plugins when it starts, so a session that was already open does not have the plugin.

> **If tool calls are blocked with client\_org\_mismatch**
>
> 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.

> **Why Claude Code cloud sessions need this**
>
> Claude Code cloud sessions run in a [cloud environment](https://code.claude.com/docs/en/cloud-environments), 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.

> **Why each environment needs its own setting**
>
> Each environment has its own list of allowed domains. Claude has no organization-wide list that adds a domain to every environment. The Cowork setting in [Allow Lumos in Cowork](#allow-lumos-in-cowork) does not apply to Claude Code cloud environments.

**Where the setting is.** Anthropic describes the setting in [Network access](https://code.claude.com/docs/en/cloud-environments#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](https://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.

> **Covering members who do not edit their own environments**
>
> 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](https://claude.ai/admin-settings/claude-code). A member who chooses one of their own environments still needs the domain in that environment.

> [!WARNING]
>
> **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:

```shell theme={null}
curl -s -o /dev/null -w '%{http_code}\n' https://mcp-governance.lumos.com/health
```

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.

> **Why Lumos cannot detect a blocked environment**
>
> 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.

### Allow Lumos in Cowork

**Why Cowork needs this.** Cowork in the cloud runs its tools and the plugin's hook in a sandbox, and the sandbox reaches only the domains that your claude.ai organization allows. If your organization does not allow `mcp-governance.lumos.com`, the plugin cannot reach Lumos from those sessions. Tool calls then run unchecked, Lumos does not record them, and neither you nor the member sees a warning. Cowork on a member's computer is not affected, because the hook runs on the computer, outside the sandbox.

This setting is separate from [Claude Code cloud environments](#allow-lumos-in-claude-code-cloud-environments). Allowing Lumos in one does not allow it in the other. If members use both, do both.

**Where the setting is.** An Owner of your claude.ai organization changes it in **Organization settings › Capabilities**, under **Code execution** ([claude.ai/admin-settings/capabilities](https://claude.ai/admin-settings/capabilities)). The setting is **Allow network egress**. Anthropic describes it in [Create and edit files with Claude](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude) and [Use Claude Cowork on Team and Enterprise plans](https://support.claude.com/en/articles/13455879-use-claude-cowork-on-team-and-enterprise-plans).

Change only what adds the domain:

* **Allow network egress to package managers only**: choose **Allow network egress to package managers and specific domains**, and add `mcp-governance.lumos.com` to the domains.
* **Allow network egress to package managers and specific domains**: add `mcp-governance.lumos.com` to the domains.
* **All domains**: change nothing. Sessions can already reach Lumos.
* **Allow network egress** turned off (the Enterprise plan default): see the next paragraph.

**If network egress is off.** **Allow network egress** is off by default on the Enterprise plan, and some organizations turn it off on purpose. Then the plugin's hook cannot reach Lumos from Cowork sessions in the cloud, so their tool calls run unchecked and neither you nor the member sees a warning. The smallest change is **Allow network egress to package managers and specific domains** with only `mcp-governance.lumos.com` added. Anthropic has no option that opens only the domains you list: this option also opens the package managers Anthropic approves, such as npm, PyPI and GitHub. See Anthropic's [list of those domains](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude).

The change applies to new Cowork sessions only. A session that is already open keeps the old setting, so start a new session.

> **What this setting does not cover**
>
> The setting covers the sandbox where Cowork runs its tools. In the cloud, the plugin's hook runs there too. Anthropic notes that it does not apply to the web fetch or web search tools, or to MCPs, including Claude in Chrome.

**Check that it works.** Start a new Cowork session in the cloud and ask Claude to run this command:

```shell theme={null}
curl -sS -o /dev/null -w '%{http_code}\n' https://mcp-governance.lumos.com/health
```

It prints `200`. If it prints `000`, Cowork cannot reach Lumos. The error line before it gives the reason: `CONNECT tunnel failed, response 403` means the domain is not allowed. Then run one tool call and check that **MCP Governance → Events** shows it with your email and **Claude Cowork** in the **Harness** column.

> **Why Lumos cannot detect a blocked Cowork setting**
>
> Lumos cannot detect a Cowork setting that blocks it: no call reaches Lumos, so nothing is recorded and no alert fires.

Run the check again after anyone changes **Allow network egress**. From time to time, check that **MCP Governance → Events** shows Cowork 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.

> **How the list applies to secrets and running sessions**
>
> 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](#rotate-the-secret), and download the zip from the rotate window.

| The window says | What to do |
| - | - |
| `Lumos could not download the plugin bundle` | Click **Try again**. If it fails again, contact Lumos support |
| `Expiry error: the secret expired. ...` | Create a new secret on the **First-Time Setup** tab and build again |
| `Format error: ...` | The secret is damaged. Create a new secret, or rotate the secret, and build again |
| A message that ends `try again, and if it fails again, contact Lumos support` | Click **Try again**. If it fails again, contact Lumos support |
| `Something went wrong while building the zip.` | Click **Try again**. If it fails again, contact Lumos support |

> **What the browser checks before it saves the zip**
>
> 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.

> **How long the old secret keeps working**
>
> 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.

> **What happens to sessions that are already running**
>
> 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](#turn-the-plugin-off-for-everyone), 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.

> **When a rollback takes effect, and removing the plugin instead**
>
> 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).

### 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**.

> **What Not available does, and what still checks tool calls**
>
> 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](https://docs.lumos.com/docs/mcp-governance-rollout.md), the MDM hook still checks Cowork and Claude Code sessions that run on that computer. See [Rolling out alongside MDM](#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:

```text theme={null}
Lumos MCP Governance blocked this tool call:
<message> (reason: <code>).
```

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.

| Reason code | Member sees | What to do |
| - | - | - |
| `secret_missing` | The plugin has no Lumos secret. Ask your admin | Build a new plugin zip, as in [Rotate the secret](#rotate-the-secret), and upload it |
| `malformed_secret`, `invalid_signature`, `unknown_kid` | Lumos could not verify the plugin's secret. Ask your admin for a fresh plugin from Lumos | Create a new plugin secret in Lumos, build the plugin zip, and upload it |
| `expired_secret` | The plugin's Lumos secret has expired. Ask your admin to rotate it and republish the plugin | Create a new secret and build the plugin as in step 1 (an expired secret cannot be rotated), and upload the zip |
| `secret_not_live` | The plugin's Lumos secret was revoked. Ask your admin to republish the plugin with the current secret | Check the secret's state in Lumos. Build a new plugin zip, as in [Rotate the secret](#rotate-the-secret), and upload it |
| `client_kind_mismatch` | The plugin's Lumos secret was made for a different kind of client. Ask your admin to rebuild the plugin with a Claude plugin secret | Build the plugin with a secret created as in step 1 |
| `client_org_missing` | Claude did not tell the plugin which Claude organization you are in. Ask your admin | Contact Lumos support |
| `client_org_mismatch` | This Claude organization is not on your company's list in Lumos. Ask your admin to add it on the MCP Governance Deployment tab | Add the Claude organization ID on the Claude plugin's **First-Time Setup** tab or on the **Claude organizations** card of its Status tab |
| `org_credentials_disabled` | Lumos MCP Governance is turned off for this organization's plugin | If **Claude plugin** is not listed on the Deployment tab, Lumos has not turned the plugin on for your organization; contact your Lumos team. If its row says **Governance off**, governance was turned off for the plugin; ask Lumos support to turn it back on |
| `email_missing` | Claude did not provide your email to the plugin. Ask your admin to enroll this device with Lumos | Claude Code in a terminal gives the plugin no email. Enroll the member's computer with Lumos through the [MDM rollout](https://docs.lumos.com/docs/mcp-governance-rollout.md). In any other session, contact Lumos support |
| `session_email_conflict` | This Claude session already reported a different email. Start a new session | The member starts a new session |
| `session_revoked` | Your admin ended this session in Lumos. Start a new session | The member starts a new session |
| `issuance_ceiling` | Your company's plugin reached its hourly limit for new sessions. Ask your admin | Review the plugin's sessions in **MCP Governance → Events**. If the volume is expected, contact Lumos support to raise the limit. If not, the secret may have leaked: rotate it |
| `org_lookup_limit` | Lumos is receiving too many sign-in checks from your company right now. Try again in five minutes | Wait five minutes. Contact Lumos support if it happens again |
| `check_limit` | Too many tool calls in the last minute from this session or this account. Wait a minute and try again | Wait a minute. If the volume is expected, contact Lumos support to raise the limit |
| `reauth` | Your Lumos session could not be renewed | Check the secret's state in Lumos. If it was rotated and its grace period has ended, upload the current plugin |
| `session_mismatch` | Lumos refused this session's credentials. Start a new session; if it happens again, tell your admin | Upload the current plugin. Contact Lumos support if it happens again |
| `harness_not_allowed` | This plugin's Lumos secret is not allowed for this kind of Claude client. Ask your admin | Upload the current plugin. Contact Lumos support if it happens again |
| `wrong_credential_kind` | The plugin sent the wrong kind of Lumos credential. Ask your admin for an updated plugin | Upload the current plugin. Contact Lumos support if it happens again |
| `lane_blocked` | Lumos refused this request. Ask your admin | Lumos has stopped the plugin for your organization; contact Lumos support |
| `assertion_invalid`, `assertion_required`, `assertion_replayed`, `email_mismatch` | Lumos could not verify this client's identity proof. Start a new session; if it happens again, tell your admin | Contact Lumos support. Claude Cowork does not send an identity proof |
| `missing_session_id`, `invalid_input`, `proof_type_unsupported`, `body_too_large`, `assertion_too_large` | Lumos could not read the plugin's sign-in request. Ask your admin for an updated plugin | Build a new plugin zip, as in [Rotate the secret](#rotate-the-secret), and upload it |
| `endpoint_insecure` | The plugin's Lumos endpoint is not secure. Ask your admin for an updated plugin | Build a new plugin zip, as in [Rotate the secret](#rotate-the-secret), and upload it |

> **How long a block lasts in a running 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**
>
> 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.

> **Reason codes not in this table**
>
> 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.

> **If Claude Code runs in a cloud environment**
>
> A Claude Code cloud environment that does not allow Lumos is one such case. See [Allow Lumos in Claude Code cloud environments](#allow-lumos-in-claude-code-cloud-environments).

> **If Cowork tool calls do not appear in Events**
>
> If Cowork sessions run tool calls but **MCP Governance → Events** shows none of them, your claude.ai organization may not allow Lumos. In a Cowork session in the cloud, run the command from [Allow Lumos in Cowork](#allow-lumos-in-cowork). If it fails with `CONNECT tunnel failed, response 403`, the domain is not allowed. Allow it, and then start a new session. This setting does not affect Cowork on a member's computer, so missing events from those sessions have another cause.
>
> Another sign is a file named `.lumos-mcp-failures` in the plugin's `lumos-relay-<uid>` directory, under the session's temporary directory (usually `/tmp`). Current plugin builds add a line to it each time a tool call runs without reaching Lumos, up to a size limit. It grows for any reason Lumos cannot be reached, so use the `curl` error to confirm the cause.
>
> Claude Code on the member's computer does not use this setting, so it can work while Cowork does not.

> **When Claude Code stops the hook after 10 seconds**
>
> 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.