APC Defines the Project Contract. MCP Defines the Tool Protocol.

A developer clarifies the distinction between APC (Agent Project Contract) and MCP (Model Context Protocol), explaining that APC defines the project contract while MCP defines the tool protocol. The developer introduces APX as a local runtime layer that bridges the two, keeping repositories small and portable while enabling external tool integration. This separation prevents project files from becoming cluttered with runtime-specific data.

A lot of confusion around agent tooling comes from mixing two different layers. APC is about the project. MCP is about external tools. APX sits in the middle and makes both useful on a daily machine. That split matters because it keeps the repository small, reviewable, and portable while still letting the runtime reach real tools when the work starts. Think of APC as the portable context layer. It tells compatible tools what a repository means: Think of MCP as the tool protocol. It tells an AI app how to talk to external capabilities: APC does not replace MCP. MCP does not replace APC. They solve different problems. If you put everything into one bucket, the bucket gets dirty fast. A repo should not have to store: Those belong with the runtime or the user machine, not with the shared project contract. That is why .apc/mcps.json is a hint file, not a secret store and not a server by itself. It can say that a filesystem MCP matters here. It should not try to become the filesystem MCP. Example: project-root/ └── .apc/ └── mcps.json That file can declare expectations. A compatible runtime still has to resolve, start, and connect the actual MCP server. APC works best when it stays narrow and stable. Good APC content: AGENTS.md .apc/agents/<slug .md .apc/skills/ .apc/project.json .apc/mcps.json Good APC content is the kind of thing you want after a fresh clone, after a laptop change, or after switching runtimes. APX is the local runtime and tooling layer. It reads APC, then performs the machine-local work that APC intentionally does not own: ~/.apx/ In other words: APC says what the project expects. APX decides how this machine fulfills it. That separation avoids a common failure mode: a project file slowly mutating into a cache, a transcript dump, and a local settings database all at once. Imagine a repo that needs a filesystem MCP and a reviewer agent. APC can describe the project shape: { "mcpServers": { "filesystem": { "command": "npx", "args": "-y", "@modelcontextprotocol/server-filesystem", "." } } } It can also define the agent contract in .apc/agents/reviewer.md . APX then does the runtime job: apx init apx agent list apx mcp check apx run reviewer "Review the open change for regressions" The repo keeps the contract. The daemon keeps the execution. This split is not just neat architecture. It lowers drift. When project meaning lives in APC, different tools can read the same source of truth. When runtime mechanics live in APX, the machine can change without rewriting the repository. When MCP stays MCP, external tool integration remains a protocol problem, not a project-format problem. That gives you three clean ownership lines: Once those lines are clear, a lot of tooling decisions get easier. You stop asking, "Where should this random state go?" and start asking a better question: "Is this project meaning, external capability, or local execution?" That question usually gives the right answer.