A growing set of recipes for common Airlock failure modes. If you hit something we haven't documented yet, the audit log and the Security → Blocks page are the two surfaces with the most diagnostic detail.
Why is my MCP token getting 403?
A bearer credential that worked yesterday and returns 403 forbidden today is almost always one of these.
"My token suddenly stopped working"
Check the Recent IP allowlist denials widget on Security → Blocks first. If your token appears there, the request was rejected before any tool ran because the source IP didn't match the configured allowlist. The widget shows the source IP and which layer denied — org (a policy that covers every token in the org) or entity (a per-service-account override).
If you don't see your token in the widget, the rejection was not an IP allowlist denial — check the audit log for any matching API_EXECUTED row with outcome: failure to find the real cause (policy DENY, budget exceeded, security block, etc.).
"I added my IP and saved, but my agent still gets 403"
The agent's egress IP almost certainly differs from the IP your browser was on when you added the entry. If the agent runs from a VPC NAT gateway, a cloud-VM, or a CI job, that's usually a different address.
Two ways to check:
- Submit a deliberately-failing call from the agent and look at the Recent IP allowlist denials widget — the denied request will show the agent's actual source IP.
- From the agent host, query an "echo" service (e.g.
curl https://api.ipify.org) to see its egress IP, then add that CIDR to the allowlist.
"My NAT IP rotated and now nothing works"
This is the expected failure mode for cloud egress that uses a pool of NAT addresses. Recovery:
- Open Security → Blocks.
- Read the source IP off the Recent IP allowlist denials widget.
- Open the relevant allowlist (org-level or service-account-level), add the new CIDR, and save.
If the NAT pool churns frequently, prefer the broader containing CIDR. A /16 covers 65,536 addresses; that's usually large enough to cover an entire cloud-provider NAT range without daily edits.
For genuinely dynamic egress (developer laptops on residential ISPs), the allowlist model is the wrong tool — leave the allowlist empty for that surface and rely on the standard policy / approval / security-block layers instead. Per-user MCP tokens are intentionally not in scope for v1 of the network-access feature.
Resetting an admin lockout
You cannot lock yourself out of the Control Room UI with the MCP IP allowlist — Cognito governs that sign-in, not the MCP token allowlist. If the lockout modal showed up because you genuinely intended to lock the connection (e.g. jump-host admins managing the policy from outside the allowed range), sign in again from the Control Room and edit the list back.
If you somehow lost Cognito access too, contact Airlock support — there's no MCP-side mitigation for a Cognito-side lockout.