Keep Secrets in APX Runtime, Not in APC

The cleanest way to think about APC and APX is this: APC is for portable project context, APX is for machine-local runtime state. Once you hold that line, MCP storage becomes much easier to reason about.

The rule is simple: if the data is safe to commit and useful to every clone of the repo, it belongs in APC. If it contains secrets, machine-specific paths, or anything that should stay local, it belongs in APX runtime storage.

That distinction matters most with MCP. An MCP server definition can look harmless on the surface, but the difference between a shared hint and a runtime secret is everything.

Three MCP scopes

APX documents three scopes for MCP config:

• shared for <repo>/.apc/mcps.json
• runtime for ~/.apx/projects/<id>/mcps.json
• global for ~/.apx/mcps.json

That split is not cosmetic. It is the storage model.

shared is for project-owned hints. It should contain server names, commands, safe args, and non-secret environment names when useful. It should not contain tokens.

runtime is where secrets belong. If an MCP server needs an API key, a personal token, or a machine-specific endpoint, that config should live in runtime scope. It stays local, not committed.

global is for machine-wide setup that is not tied to one project. Same rule: local if needed, but not project context.

Why the split matters

People often try to solve MCP setup by putting everything into the repo. That feels convenient until the first secret leaks into git history or one teammate cannot safely use the same config.

The better model is boring:

• APC carries the project contract.
• APX carries the machine state.
• MCP config follows the same boundary.

That gives you portability without leaking credentials. A teammate can clone the repo and immediately see which MCP servers matter. The secret-bearing parts can still stay local and be loaded by APX when the project runs.

The practical rule

Use this filter:

• Does the whole team need it, and is it safe to commit? Put it in shared APC scope.
• Does it include a token, key, or machine-specific credential? Put it in runtime scope.
• Is it personal machine setup, not project context? Keep it in global or leave it local.

That rule keeps the repo clean and the runtime useful.

What this looks like in APX

APX is the layer that makes the split operational. It reads the committed project context, merges MCP config across scopes, and keeps runtime state under ~/.apx/. That way the same project can stay portable while still using private services safely.

This is one of those places where the architecture is the feature. The user-facing benefit is not the folder layout itself. The benefit is that you can share project context without turning the repository into a secret bucket.

Common mistake

The common mistake is mixing up project knowledge and private access.

For example:

• a filesystem MCP for the repo is project knowledge
• a personal API token for that filesystem server is private access

The first can live in APC. The second should stay in APX runtime scope.

If you keep those separate, the project stays reproducible and the secret stays local.

Bottom line

APC is the portable context layer. APX is the runtime layer. MCP config should follow the same split:

• shared for safe project hints
• runtime for secrets
• global for machine-wide local setup

That is the smallest rule that prevents the biggest mistake. Keep project meaning in the repo. Keep credentials in the runtime.

Comments

[Alex Shev]

The APC/APX split is a clean mental model. Portable context should be safe to clone and review; runtime state should stay local and machine-specific. That boundary is especially important with agents because anything placed in project context eventually becomes model input, not just documentation.