heimdall

Heimdall is one binary serving several separately scoped MCP servers, one per profile: asc-monetization, asc-distribution, asc-testflight and so on. Apple's API is 982 operations, which costs more in tool definitions than most context windows can spare, so a session carries one or a few profiles rather than all of them.

The credential boundary

Going after the API key is the single most common way a session goes wrong: in recorded runs, of the sessions that left the tools behind, the largest group went hunting for the private key and the next largest called Apple directly with curl.

Neither is the way through, and the reason is worth stating exactly, because the convenient version of it is false:

• The JWT is minted inside the server, per request, from a key the server reads at startup — on macOS out of the Keychain, elsewhere from a .p8 on disk. A shell running as this user can reach that key: security find-generic-password -w prints it to whatever asks. So this is a rule, not a wall, and a session that tests it will find it gives way.
• Which is exactly why crossing it is the wrong move rather than an impossible one. A token signed outside the server skips the rate limiter, the write-confirmation gate, the dry-run path and the response shaping — every guard this server exists to apply. curl https://api.appstoreconnect.apple.com/... is not the fallback when a tool returns an error: unsigned it returns 401, and hand-signed it runs unguarded against real App Store data.

So when an App Store Connect tool fails, the next step is always another tool call — asc__status to check the connection, asc__search_tools to find a different operation — never the shell. If the credentials genuinely are not configured, asc__status says so, and the fix is setup (below), which only the user can run.

Least privilege

No endpoint returns a key's role, so a 403 partway through a task is often the first anyone learns the key is narrower than assumed. Before telling the user their key is broken or asking them to mint an Admin one, call asc__status with check_capabilities: true — one cheap probe per role family (reports, metadata, reviews, userManagement, provisioning), each ok / forbidden / unauthorized / agreement / unknown. unknown means the probe was inconclusive (network, a 5xx, no app to test against) — agreement means the account has an unsigned or expired agreement, the same 403 a narrow role gives for an unrelated reason. Never read either as a denial that a wider key would fix — agreement in particular is not a role problem at all, and no key clears it.