MCP Scopes Are Trust Boundaries, Not Settings
The easiest way to misuse MCP in APC/APX is to treat scope like UI decoration. It is not. Scope decides where the trust boundary lives.
APX exposes three MCP scopes in its UI: runtime, shared, and global. The names are simple, but they describe different ownership rules:
- Runtime: this project only, with secrets, not committed, stored under
~/.apx/projects/<id>/mcps.json - Shared: this project only, committeable, no secrets, stored in
.apc/mcps.json - Global: all projects on this machine, stored in
~/.apx/mcps.json
That split is the point. Each scope answers a different question.
Runtime: local, secret, disposable
Runtime scope is for MCP config that depends on the machine or the current operator. If a server needs headers, tokens, or any credential that should not travel in git, runtime is the right home.
This scope should not carry project meaning. It is not portable by design. That is a feature, not a flaw. If the config is safe to lose with a machine reset, runtime is enough.
Shared: project-level, reviewable, portable
Shared scope is the one APC can carry.
If an MCP server belongs to the repo and does not need secrets, it should live in .apc/mcps.json. That makes the choice visible in code review, clone-safe, and tool-neutral. Another runtime can read the same project contract without rebuilding it from memory.
This is the scope that keeps APC useful. The repo says, "we expect this tool here." It does not say, "this laptop happened to be configured once."
Global: machine defaults, not project truth
Global scope is useful, but easy to overuse. It is for helpers that make sense across many repos on one machine. Think of a local utility server or a universal tool you want available everywhere.
The risk is subtle: once something becomes global, it can hide missing project context. A repo may appear to work because your machine has a default, while the repo itself carries no portable intent. That makes onboarding fragile.
Scope is not transport
One more detail matters: scope and transport are different decisions. Transport says how the server connects, such as stdio or HTTP. Scope says who owns the configuration and where it lives.
Mix those up and the model gets fuzzy fast. Keep them separate and the system stays legible.
How to choose
A quick test usually works:
- Secret or machine-specific? Runtime.
- Project-level and safe to commit? Shared.
- Reused across many repos on one machine? Global.
If you need to think longer than that, the answer is probably shared versus runtime. Ask one more question: "Would I want this exact choice to survive a clone?" If yes, keep it in APC. If no, keep it in APX.
Common mistake
The worst pattern is putting the same MCP server in all three places.
Then you get conflicts, hidden precedence, and mystery behavior. APX already hints at that in the UI by showing conflicts. That warning matters. It means the machine can merge views, but you still need a clear source of truth.
Pick one scope. Keep one owner. Let the others stay empty unless they truly add value.
Bottom line
MCP scopes are not preferences. They are boundaries.
Runtime protects secrets. Shared preserves project meaning. Global serves machine convenience. When you map each MCP to the right scope, APC stays portable and APX stays predictable.
Top comments (3)
Scopes as trust boundaries is the right framing. If a scope is treated like a preference, people will broaden it whenever the agent gets stuck.
The safer design is to make scope changes visible and intentional: why does the tool need this access, for how long, and what action becomes possible after granting it. That turns permissions into a workflow decision instead of background configuration.
Exactly. The key test is whether the scope change has a reviewable reason, an owner, and a lifetime. If the answer is only ‘the agent got stuck,’ that is pressure to redesign the workflow, not a reason to widen access.
Exactly. Scope expansion should feel more like a change request than a runtime convenience.
The "agent got stuck" signal is useful, but not as permission. It should trigger a design question: is the workflow missing a narrower tool, a better handoff, or a human checkpoint?