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:
~/.apx/projects/<id>/mcps.json
.apc/mcps.json
~/.apx/mcps.json
That split is the point. Each scope answers a different question.
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 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 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.
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.
A quick test usually works:
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. 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.
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.