Command overview
beacon mcp managed pushes MCP servers an administrator chooses to every account on a Mac or
Linux machine, for Claude Code and Codex CLI. People do not have to do anything, and they keep
every MCP server they add themselves.
Command syntax
apply the complete list of servers, and each
run makes the machine match it. Adding a server to the list pushes it, and taking one out removes
it. Running apply again with the same list changes nothing.
apply and remove need root. status does not. None of the three makes a network request or
reads a Beacon account token.
Server list
The list is a JSON object with one entry per server underservers:
servers.json
An empty list,
{"servers": {}}, removes every server Beacon pushed. Any other field is refused,
so a typo fails the script instead of pushing a server without it.
Only remote servers are supported. Claude Code’s managed server setting accepts nothing else: no
command (stdio) servers and no ${VAR} expansion, so apply refuses both.
Where the servers go
Each runtime gets the servers through its own machine-wide configuration. In both, the pushed servers are added to what people configure. They do not replace it.
Claude Code reads
managedMcpServers from its managed settings, in version 2.1.259 or later.
Earlier versions ignore it. People cannot remove a pushed server with claude mcp remove, but
they can turn it off for themselves in /mcp. Beacon does not use managed-mcp.json, which takes
exclusive control and stops every server people add themselves from loading.
Codex CLI reads /etc/codex/config.toml as its system configuration layer. Codex merges it
with each person’s ~/.codex/config.toml table by table, so the pushed servers load next to
people’s own. In Codex, every pushed server’s name starts with org-: linear in the list is
org-linear in Codex. Because of the table-by-table merge, a pushed [mcp_servers.linear] would
merge into a person’s own linear server. If theirs runs a local command, the merged entry has
both a command and a URL, and Codex then refuses to load that person’s whole configuration. The
prefix keeps pushed servers separate, so someone with their own linear sees both.
A person’s own settings take precedence: they can turn off a pushed server with
enabled = false in their own [mcp_servers.org-<name>] table. Beacon changes only the tables
that carry its marker comment. Everything else in the file, including servers someone else wrote
and comments around Beacon’s tables, is kept byte for byte. If the file already has an org-
server of the same name that Beacon did not write, apply leaves it alone and reports it.
People pick up a change the next time they start Claude Code or Codex.
Output
apply and remove print one row per runtime:
The command exits non-zero when a runtime failed, so the MDM script reports it. The other runtime
is still updated. A Codex config that is not valid TOML, or a file that is a symlink, is left
unchanged and reported as
failed.
status lists the servers Beacon pushed to each runtime, and warns about settings that stop them
from loading:
- On macOS, a configuration profile that delivers Claude Code managed preferences
(
com.anthropic.claudecode). Claude Code then reads only that profile and ignores managed-settings files, Beacon’s included, unless the profile setsmanagedSourcesBehaviorto"merge". Server-managed settings from the Claude admin console have the same effect, and Beacon cannot detect them. - An
[mcp_servers]allowlist in/etc/codex/requirements.toml. Codex disables every server it does not list, pushed servers included.
Examples
Push a list from a file:Uninstall
Uninstalling Beacon leaves pushed servers in place, because they are the runtimes’ own configuration. To take them away, stop the MDM script that runsapply first, so it cannot push
them again, then run sudo beacon mcp managed remove and uninstall.