Deploy MCP Governance across your fleet
MCP Governance records and controls every MCP tool call your employees’ AI agents make. This guide is how you get it onto a whole company rather than one machine at a time.Looking for the Lumos MCP servers?This page is about governing the MCP servers your employees’ agents call. If you are trying to connect an AI client to Lumos, see the Lumos User MCP Server or the Lumos Admin MCP Server.
Early access. The MDM steps below are written from the product’s design and have not yet been verified end to end. Lumos is looking for design partners to run the first rollouts. Talk to your Lumos contact before scoping this to a large fleet.
Pick your path first
There are two ways to install MCP Governance. Your choice determines whether your policies can be trusted.
Per-user install is a pilot tool. The install page issues an enrollment token scoped to that one person, and they run the command themselves. Two consequences: the email the agent reports comes from a file in that person’s own home directory, which they can edit, and the person who installed the hooks can remove them.
That is fine for a proof of concept, where the point is to see what your agents are doing. It is not a basis for a policy that says this person may not call that tool. If you intend to block anything, deploy by MDM.
The rest of this guide assumes MDM.
Before you begin
You need:- A Lumos account with Organization Admin, and MCP Governance enabled on your domain.
- Jamf, Intune or Kandji, with the authority to scope a script and a configuration profile to your fleet.
- Claude Code or Codex on the target machines.
- A device inventory export from your MDM as CSV, carrying at minimum each device’s serial and its owner’s Okta user id or Entra object id.
How it works
Your MDM does two things: it runs a one-time enrollment script on each device, and it pushes a hook config for each AI agent in use. Nothing from Lumos is installed — the script writes a single device token, and the hook is acurl invocation.
From then on, every MCP tool call on that device is checked against your policies before it runs and logged after it runs, attributed to the person your inventory names for that machine.
Devices move through three states, visible on the Devices tab:
- Pending — the device is in your uploaded inventory but the enrollment script has not run on it yet.
- Enrolled — the script has run, the device holds a token, and its tool calls are being attributed to its owner.
- Refused — a machine tried to enroll with a serial that is not in your inventory.
1. Import your device inventory
Export your device list from your MDM as CSV and upload it in Lumos at MCP tool usage → Devices → Import.
Header names are case-insensitive and order does not matter. Lumos previews the import before writing anything.
Re-importing updates each listed serial’s owner,
udid, email, and name. A blank udid or email cell clears that value, but a blank name never does. An owner an admin assigned by hand is kept. A Retired device whose serial is in the file returns to Pending, so leave retired machines out of the file. A Refused serial that is now in the file also becomes Pending and can enroll. Other statuses, and each device’s token and timestamps, stay as they are.
A name from the file wins over the name the machine reports when it enrolls. A blank name cell never erases a name Lumos already has, so a file without names leaves existing names in place. On macOS, the enrollment script reports the machine’s Computer Name (the name your MDM shows) rather than its DNS hostname.
Every device you upload lands as Pending. Scope the import to the machines you intend to govern: a serial that is not in the inventory cannot enroll.
2. Create an enrollment token
In Lumos, go to Settings → API Tokens → Add and choose MCP Enrollment Token. Name it after the rollout, pick a lifetime, and copy thelmcpe_ value — it is shown once.
Only a Lumos admin can create one. A single token enrolls as many devices as you need, but only serials that are already in your inventory.
3. Push the enrollment script
The script runs once per device, as root. It writes the device token to/Library/Lumos/device-token and nothing else.
- Jamf
- Intune
- Kandji
Go to Settings → Computer Management → Scripts and create a script:Then create a Policy that runs it:
- Scope: the smart group covering your fleet — not a static list, or new hires will silently miss enrollment.
- Parameter 4: the
lmcpe_token. Keeping it in the policy rather than the script means the token is not sitting in your script library. - Trigger: recurring check-in, plus enrollment complete so new machines pick it up automatically.
- Execution frequency: once per computer.
4. Push the hook config
Download the config for each agent in use and push it as managed settings. Do not edit the command inside it.
Append
?capture=none to the URL if tool arguments must never leave the device. Policies that match on tool input will then never match.
- Jamf
- Intune
- Kandji
Push it as a configuration profile scoped to the same smart group as the enrollment policy.
5. Verify
A device is done when its row on the Devices tab reads Enrolled and its tool calls appear on MCP tool usage under the right person. Compare your MDM’s own success count against the enrolled count in Lumos — a smart group in Jamf, the script success count in Intune, the Library item status in Kandji. Investigate anything that stays Pending: that means the script has not run on that device yet, so start with the scope and your MDM’s run log.The rollout, in four stages
Enrollment is the mechanical part. Getting from “installed” to “enforcing” without breaking anyone’s work is the part worth pacing.1
Pilot (about a week)
Do: 5 to 10 devices, chosen from people who use agents heavily. Enroll them through the MDM path, not the install page, so you are testing what you will actually run.Don’t: write any policies.Move on when: every pilot device reads Enrolled, tool calls are appearing under the right person, and you recognise the MCP servers showing up in Inventory.
2
Fleet enrollment (one to two weeks)
Do: import the full device inventory, mint an enrollment token, scope the enrollment script and the hook config to the whole fleet.Don’t: write any policies yet. Nothing blocks at this stage, by design — you are buying coverage, not control.Move on when: the Devices tab shows the enrolled count matching your fleet, every Refused row has been reviewed — moved to Pending if you recognise it, investigated if you don’t — and no row has been Pending for more than a few days.
3
Observe (at least two weeks)
Do: read the events. Which MCP servers are in use, by whom, and which tools. Mark servers Approved or leave them Needs Review in Inventory. Write your allow policies now — they change nothing on their own, and writing them against real observed usage is how you avoid blocking work you didn’t know existed.Don’t: write deny policies.Move on when: every MCP server your people actually use has been reviewed and given a status, and you can name the handful of tool calls you intend to stop.
4
Enforce
Do: add deny policies, narrowest first — a specific tool on a specific server, or a specific group. Watch the events for a week before widening. A blocked call fails with the policy name in the message, so the employee knows why and who to ask.Don’t: open with an org-wide default-deny. Start with the calls you can justify blocking to the person they affect.Done when: your deny policies hold, the blocks you see are the ones you intended, and support volume has settled.
Keeping it running
- New hires. A new device appears in your MDM, flows into the Lumos inventory, and the enrollment policy runs on it. Check the policy is scoped to a dynamic group rather than a static list of machines.
- Token expiry. Enrollment tokens have a lifetime. Devices already enrolled keep working when a token expires; new devices stop enrolling. Diarise the expiry.
- Re-imaged or replaced machines. Re-running the enrollment script re-enrolls the device with a fresh token.
- Lost, stolen or offboarded machines. Revoke the device on the Devices tab. Revocation is per device and takes effect immediately: that machine’s token stops working and nothing else in your fleet is affected. Make this a step in your existing lost-device and offboarding runbooks.
Troubleshooting
A device shows Refused
A machine presented a serial that is not in your inventory. Add the serial to your CSV and re-import, or move the row to Pending from the Devices tab, and it becomes eligible to enroll.A row stays Pending
The enrollment script has not run on that device yet. Check your MDM policy scope and its run log.An Enrolled device has a rising refusal count
A second device is presenting that serial, or the script ran twice. Revoke the device, then let the script re-run.The enrollment token has a rising refusal count
Devices outside your inventory are presenting it. Check your MDM scope, and revoke and re-mint the token if it has leaked.The script logs “the enrollment token is unknown, expired or revoked”
The token is dead. Create a new one and update your MDM policy.A device shows Enrolled but no tool calls appear
Claude Code is ignoring the hook config your MDM pushed, because your organization has server-managed settings in the Claude console. Run/status in Claude Code — the file is listed under “Skipped sources”. Apply one of the console fixes, then restart Claude Code.