alirezarezvani/claude-skills / engineering/skills/mcp-oauth-triage
mcp-oauth-triage
FlaggedUse when an MCP connector that used to authenticate now fails (tool calls 401 after a good token exchange, breaks after refresh, returns another account's data), before changing code. Classifies the fault with oauth_triage.py.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 3.8 KB |
| SKILL.md | skill md | 14.2 KB |
| assets/fixtures/binding_record.json | config | 220 B |
| assets/fixtures/clean_events.jsonl | other | 174 B |
| assets/fixtures/clean_record.json | config | 236 B |
| assets/fixtures/envelope_record.json | config | 179 B |
| assets/fixtures/expiry_record.json | config | 123 B |
| assets/fixtures/negative_cache_events.jsonl | other | 139 B |
| assets/fixtures/negative_cache_record.json | config | 128 B |
| assets/fixtures/rotation_events.jsonl | other | 300 B |
| assets/fixtures/rotation_record.json | config | 109 B |
| examples/rotation-clobber-walkthrough.md | markdown | 4.8 KB |
| expected_outputs/verdicts.json | config | 1.3 KB |
| references/failure-classes.md | markdown | 7.1 KB |
| references/verification-recipes.md | markdown | 3.8 KB |
| scripts/oauth_triage.py | script | 19.8 KB |
| scripts/run_fixtures.py | script | 5.2 KB |
references/verification-recipes.md
View on GitHub# Verification Recipes
A login proves consent. It does not prove the connector survives a refresh, and refresh is where four of
the five classes live. Use these recipes to produce evidence a reviewer can check without trusting you.
## Recipe 1: Record shape
```bash
python3 scripts/oauth_triage.py --token-file ./token.json --expect-flat --expect-absolute-expiry
```
Expect exit 0. A non-zero exit names the field causing it. Run this after any change to a serialiser, a
dataclass, or a model alias.
## Recipe 2: Single refresher
The goal is to prove exactly one exchange happens per credential per expiry window.
```bash
python3 scripts/oauth_triage.py --token-file ./token.json --log ./connector.jsonl --json \
| python3 -c "import json,sys; d=json.load(sys.stdin); print(d['primary_class'], d['confidence'])"
```
Then, with the connector under normal load, count exchange events in one window:
```bash
python3 - <<'PY'
import json
from collections import Counter
events = [json.loads(l) for l in open('connector.jsonl') if l.strip()]
exchanges = [e for e in events if str(e.get('event', '')).lower() in
{'exchange', 'refresh', 'token_exchange', 'token_refresh'}]
print('exchanges:', len(exchanges))
print('distinct credentials:', len({e.get('credential') or e.get('account_id') or '?' for e in exchanges}))
PY
```
One exchange per credential per window is correct. Two or more inside the same window is class C, even
if the connector currently works, because the next rotation will decide a winner you cannot control.
## Recipe 3: Round trip across a refresh
This is the only recipe that proves a fix. Record all three results.
```bash
# 1. Call through the surface that was failing, before any refresh
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" "$SURFACE"
# 2. Force one refresh, then call again
# (force by expiring the record or by invoking the connector's refresh entry point)
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" "$SURFACE"
# 3. Wait for the next scheduled refresh, then call a third time
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" "$SURFACE"
```
Two of three is not a fix. A pattern of 200, 200, 401 means the fault is downstream of the first
refresh, which usually points at class B or C rather than the original symptom.
## Recipe 4: Binding comparison
```bash
# What the token claims
python3 scripts/oauth_triage.py --token-file ./token.json --expect-aud "$SURFACE" --json
# What the surface advertises
curl -s "$SURFACE/.well-known/oauth-protected-resource" | python3 -m json.tool
```
Compare `aud` against the advertised `resource`, and `iss` against the advertised authorization server.
A mismatch on either is class D and no amount of re-authentication will change it.
## Recipe 5: Negative cache isolation
```bash
# 1. Snapshot the marker state
python3 scripts/oauth_triage.py --token-file ./token.json --json | grep -i cache
# 2. Clear only the marker, leave the credential untouched, retry
# 3. If service returns, the class is E, and the marker needs a scope
```
Do not delete the credential to test this. Deleting the credential confirms nothing and costs a login.
## Minimum evidence pack for a fix report
| Item | Command |
|---|---|
| Pre-fix verdict | `oauth_triage.py --token-file old.json --log old.jsonl --json` |
| Post-fix verdict | `oauth_triage.py --token-file new.json --log new.jsonl --json` |
| Exchange count under load | Recipe 2 |
| Round trip | Recipe 3, all three codes |
| Diff of the change | `git diff` of the writer, the reader, and the lock |
| Scope of any cache or marker touched | the exact path or key, and why that scope |
Six rows, six commands. If a row is empty, the fix is not verified, whatever the connector appears to do
in the moment.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |