Verified Agent Skill record

MCP Oauth Triage

Diagnose why an OAuth-backed MCP connector that used to authenticate now fails (401s after a good token exchange, breaks after refresh, or another account's data) by classifying the fault into one of five classes with oauth_triage.py, before changing code and again before declaring the fix done.

Tasks

Classify a previously working MCP connector's OAuth failure by running python3 scripts/oauth_triage.py with a stored token record and an ordered connector log before changing any code
Match the classifier's primary fault class (envelope mismatch, expiry semantics, rotation clobber, binding fault, or poisoned negative cache) to its documented fix and confirm it with the class's discriminator first
Verify a fix with one full round trip: a call succeeds before a refresh, after a refresh, and after a second refresh before declaring the connector fixed
Redact a token record before sharing it in a ticket or chat using python3 scripts/oauth_triage.py --token-file ./token.json --redact

Inputs

A stored token record (the JSON the connector reads back, exactly as written)
An ordered connector log with timestamps for exchange, store, load, call, and error events
Timing information: how long after a successful call the failure appears
Optional flags such as --json, --redact, --expect-flat, and --expect-absolute-expiry

Outputs

A line-oriented report or JSON verdict containing primary_class, confidence, findings with class, severity, and evidence, next_probe, and exit_code
An exit code: 0 (no defect signals found in the supplied artifacts), 1 (suspect findings only), or 2 (a defect class is confirmed by the artifacts)

Limitations and checks

Not for first-time setup that never worked; that belongs with mcp-server-builder and this skill assumes a working state existed and was lost
Exit 0 is not a health check; if the symptom is live and the classifier is clean, the artifacts are wrong
The tool makes no network calls, so it only evaluates supplied artifacts, not live provider behavior
The classifier exits 0 against the post-fix record
The record holds one absolute integer expiry, or the reader explicitly accepts relative TTLs
Exactly one refresher exists per credential, and a concurrency probe shows no parallel exchange
The stored refresh token matches the one returned by the most recent successful exchange
A call through the previously failing surface succeeds before a refresh and again after it