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

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.

The short version

Think of APC as the portable context layer.

It tells compatible tools what a repository means:

• which agents exist


• which rules matter


• which skills belong to the project


• which MCP servers the project expects


• which curated facts should survive beyond one session

Think of MCP as the tool protocol.

It tells an AI app how to talk to external capabilities:

• tools


• resources


• prompts


• transports


• schemas


• request and response flow

APC does not replace MCP. MCP does not replace APC. They solve different problems.

Why the distinction matters

If you put everything into one bucket, the bucket gets dirty fast.

A repo should not have to store:

• API keys


• bearer tokens


• session logs


• transient runtime state


• machine-specific absolute paths

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.

What APC should contain

APC works best when it stays narrow and stable.

Good APC content:

• root project contract in AGENTS.md
  


• structured agents in .apc/agents/<slug>.md
  


• reusable skills in .apc/skills/
  


• project metadata in .apc/project.json
  


• curated memory when it is safe to share


• MCP expectations in .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.

What APX should do

APX is the local runtime and tooling layer.

It reads APC, then performs the machine-local work that APC intentionally does not own:

• start the daemon


• run agents


• manage sessions and messages


• keep runtime state local under ~/.apx/
  


• resolve and merge MCP sources


• dispatch across runtimes and engines

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.

A concrete workflow

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.

The deeper reason

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:

• APC: project meaning


• MCP: external capability protocol


• APX: local execution layer

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.