{"slug": "apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps", "title": "APX `mcp check` Is the Fastest Way to Debug Shadowed MCPs", "summary": "APX, the local runtime and tooling layer for the APC portable context layer, introduces `apx mcp check` to debug shadowed MCPs by showing source files, active entries after merge, and conflicts. The command reveals which MCP configuration won and which got shadowed, addressing the limitation of `apx mcp list` which only shows the merged result. APX enforces a priority order of runtime > shared > global, and `mcp check` makes conflicts visible to help developers identify unexpected overrides.", "body_md": "`mcp check`\n\nIs the Fastest Way to Debug Shadowed MCPs\nAPC is the portable context layer. APX is the local runtime and tooling layer that makes APC useful every day. When an MCP setup feels wrong, the fastest fix is usually not to stare at the final list of servers. It is to inspect how APX merged the sources.\n\nThat is why `apx mcp check`\n\nmatters. It shows the source files, the active entries after merge, and any conflicts. In other words, it answers the real question: *which MCP won, and what got shadowed?*\n\n`list`\n\nis not enough\n`apx mcp list`\n\nis useful, but it only shows the merged result. That is good for a quick inventory and bad for debugging drift. If the same MCP name exists in more than one scope, the final list hides the path that produced it.\n\nA clean list can still hide a bad setup. For example:\n\n`.apc/mcps.json`\n\n`~/.apx/projects/<id>/mcps.json`\n\n`~/.apx/mcps.json`\n\nThe name looks fine. The source may not be the one you expected.\n\nAPX is explicit about priority: `runtime > shared > global`\n\n. The runtime file wins when names collide, then the shared APC file, then the machine-wide global file. The tests cover that chain, and the CLI prints conflicts on purpose.\n\nThat means two things:\n\nIf a server disappears or behaves differently than expected, do not guess. Ask APX which source won.\n\n`mcp check`\n\nshows\n`apx mcp check`\n\ngives you three useful views at once:\n\nThat is the right level for debugging. It tells you whether APX is reading the repo file, the runtime file, or the global file. It also tells you whether an entry is APX-owned or coming from a foreign IDE config that APX only reads advisory.\n\nA typical flow looks like this:\n\n```\napx mcp check --project iacrmar\napx mcp list --scope runtime --project iacrmar\napx mcp list --scope shared --project iacrmar\n```\n\nUse `check`\n\nfirst. Use `list`\n\nsecond, when you already know where to look.\n\nImagine you add `github`\n\nin shared scope because you want every clone of the repo to know the server exists. Later, you add another `github`\n\nentry in runtime scope because this machine needs a token.\n\nThat is not a bug. It is a layered override. But if you forget the runtime copy exists, you may edit the shared file and still see the runtime version win. The project looks unchanged, because APX is doing what the merge rule says.\n\n`apx mcp check`\n\nmakes that obvious. It will show the runtime entry as the winner and report the shared entry as the loser.\n\nAPX can inspect foreign MCP configs from other tools, but it will not rewrite them. The code is careful here: if an MCP comes from a foreign source, APX tells you to change it in that tool's config instead. That is a good boundary. APX should manage APX-owned scopes, not silently mutate somebody else's setup.\n\nSo the practical rule is simple:\n\nAPC stays portable because it only carries the shared part of the story. If a token or a local endpoint sneaks into the repo, the clone-safe contract breaks. APX protects that contract by keeping runtime state local and by making conflicts visible instead of hidden.\n\nThat is the deeper reason `mcp check`\n\nexists. It is not a status screen. It is a sanity check for the boundary between portable context and local execution.\n\nWhen MCP behavior looks wrong, start with `apx mcp check`\n\n.\n\nIt shows the files, the winners, and the conflicts. That is usually enough to explain the issue in one pass, without guessing which layer won or which file got shadowed.", "url": "https://wpnews.pro/news/apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps", "canonical_source": "https://dev.to/agentprojectcontext/apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps-4kn1", "published_at": "2026-06-27 12:02:23+00:00", "updated_at": "2026-06-27 12:03:26.889229+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure", "ai-agents"], "entities": ["APX", "APC", "MCP"], "alternates": {"html": "https://wpnews.pro/news/apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps", "markdown": "https://wpnews.pro/news/apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps.md", "text": "https://wpnews.pro/news/apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps.txt", "jsonld": "https://wpnews.pro/news/apx-mcp-check-is-the-fastest-way-to-debug-shadowed-mcps.jsonld"}}