Troubleshooting
Connecting
Section titled “Connecting”The connector won’t add / OAuth never completes.
Check the URL is exactly https://iiiftools.pangur.io/mcp. The sign-in that opens must be
completed with your iiiftools account (register first at
iiiftools.pangur.io if you haven’t).
Claude Code: invalid_scope during OAuth.
Shouldn’t happen — the auth realm auto-patches Claude Code’s dynamically-registered clients
with the offline_access scope within seconds of registration. If you hit it, retry once;
if it persists, the reconciler service may be down.
OAuth over SSH never finishes. The loopback callback lands on the wrong machine. Use a headless login (print the auth URL, finish on your own device) or connect via a claude.ai connector instead — see Coding agents.
Resolving
Section titled “Resolving”“could not resolve a IIIF manifest for …” The URL didn’t match a rule and the generic fallback found nothing. Check it is a viewer URL (a specific document), not a search or exhibition page — hub pages return a list of resolvable links found on the page; use one of those. If the library is genuinely unsupported, add a repository rule and dry-run it with the Test box.
“extraction … is expired — call resolve again.”
Extractions live 2 hours. Resolving the same URL again is cheap and gives a fresh
extraction_id.
Images
Section titled “Images”The page image is too small to read the script.
That’s expected for a full folio delivered inline — it is downscaled to fit a vision model’s
input budget (the response’s scale_of_native tells you how far below native it is). Use
get_canvas_tiles: native-resolution tiles in reading order, four per call. Don’t try to
transcribe dense hands from a downscaled full page.
The ink is faded/browned and hard to read even at native resolution.
Re-request the tiles with enhance="clahe_red" (adaptive contrast on the red channel —
strongest lift for iron-gall ink on parchment), or "clahe" / "stretch" for general
low-contrast pages. Enhancement is a derived copy; the original download is untouched.
Inline image refused as too large.
The page is dense enough that even downscaled it exceeds the inline budget. Ask for a
region crop of the part you care about, or switch to delivery="url".
A signed link returns HTTP 410. The link expired (~30 min), the extraction was released, or the token was altered. Re-request the image — a fresh link is issued for the already-downloaded file.
Downloads fail from one library only.
Some IIIF servers only serve sizes advertised in info.json, rate-limit, or return HTML
error pages with HTTP 200. These are handled by
per-repository quirks — if a new library
misbehaves, set honor_info_sizes or rate_limit_ms on its rule.
“temporary image store is full.” The 5 GB cap was reached. Release finished extractions from the dashboard (or wait for the TTL sweeper) and retry.