{"slug": "apc-defines-the-project-contract-mcp-defines-the-tool-protocol", "title": "APC Defines the Project Contract. MCP Defines the Tool Protocol.", "summary": "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.", "body_md": "A lot of confusion around agent tooling comes from mixing two different layers.\n\nAPC is about the project. MCP is about external tools. APX sits in the middle and makes both useful on a daily machine.\n\nThat split matters because it keeps the repository small, reviewable, and portable while still letting the runtime reach real tools when the work starts.\n\nThink of APC as the portable context layer.\n\nIt tells compatible tools what a repository means:\n\nThink of MCP as the tool protocol.\n\nIt tells an AI app how to talk to external capabilities:\n\nAPC does not replace MCP. MCP does not replace APC. They solve different problems.\n\nIf you put everything into one bucket, the bucket gets dirty fast.\n\nA repo should not have to store:\n\nThose belong with the runtime or the user machine, not with the shared project contract.\n\nThat is why `.apc/mcps.json`\n\nis 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.\n\nExample:\n\n```\nproject-root/\n└── .apc/\n    └── mcps.json\n```\n\nThat file can declare expectations. A compatible runtime still has to resolve, start, and connect the actual MCP server.\n\nAPC works best when it stays narrow and stable.\n\nGood APC content:\n\n`AGENTS.md`\n\n`.apc/agents/<slug>.md`\n\n`.apc/skills/`\n\n`.apc/project.json`\n\n`.apc/mcps.json`\n\nGood APC content is the kind of thing you want after a fresh clone, after a laptop change, or after switching runtimes.\n\nAPX is the local runtime and tooling layer.\n\nIt reads APC, then performs the machine-local work that APC intentionally does not own:\n\n`~/.apx/`\n\nIn other words: APC says what the project expects. APX decides how this machine fulfills it.\n\nThat 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.\n\nImagine a repo that needs a filesystem MCP and a reviewer agent.\n\nAPC can describe the project shape:\n\n```\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"]\n    }\n  }\n}\n```\n\nIt can also define the agent contract in `.apc/agents/reviewer.md`\n\n.\n\nAPX then does the runtime job:\n\n```\napx init\napx agent list\napx mcp check\napx run reviewer \"Review the open change for regressions\"\n```\n\nThe repo keeps the contract. The daemon keeps the execution.\n\nThis split is not just neat architecture.\n\nIt lowers drift.\n\nWhen 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.\n\nThat gives you three clean ownership lines:\n\nOnce 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?\"\n\nThat question usually gives the right answer.", "url": "https://wpnews.pro/news/apc-defines-the-project-contract-mcp-defines-the-tool-protocol", "canonical_source": "https://dev.to/agentprojectcontext/apc-defines-the-project-contract-mcp-defines-the-tool-protocol-3aof", "published_at": "2026-06-30 12:02:56+00:00", "updated_at": "2026-06-30 12:18:55.696653+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["APC", "MCP", "APX"], "alternates": {"html": "https://wpnews.pro/news/apc-defines-the-project-contract-mcp-defines-the-tool-protocol", "markdown": "https://wpnews.pro/news/apc-defines-the-project-contract-mcp-defines-the-tool-protocol.md", "text": "https://wpnews.pro/news/apc-defines-the-project-contract-mcp-defines-the-tool-protocol.txt", "jsonld": "https://wpnews.pro/news/apc-defines-the-project-contract-mcp-defines-the-tool-protocol.jsonld"}}