Model Context Protocol (MCP)¶

iiiris can expose its read-only IIIF capabilities to AI agents over the Model Context Protocol. An MCP host — Claude Desktop, Claude Code, or the Claude API's remote-MCP connector — can then browse a collection, read image metadata, and pull image regions as pictures through typed tool calls, instead of hand-driving the raw HTTP API.

This is off by default: MCP is a new protocol surface and a new dependency, so it mounts nothing unless you turn it on. It does not affect the zero-config image path, the Presentation API, or Content State.

Enabling it¶

mcp:
  enabled: true    # mounts the /mcp Streamable HTTP endpoint (default false)

When enabled, iiiris serves a single Streamable HTTP MCP endpoint at /mcp on the main listener. That is the URL you give an MCP host.

Connecting a host¶

Claude API remote-MCP connector — point it at the URL:

"mcp_servers": [
  { "type": "url", "url": "https://your-iiiris-host/mcp", "name": "iiiris" }
]

(with an mcp_toolset entry referencing iiiris, per the connector docs).

Claude Desktop / Code — add a URL MCP server pointing at https://your-iiiris-host/mcp.

Tools¶

Tool	What it does	Returns
`browse`	Lists the immediate children of a source path (empty path = root).	JSON entries: `{identifier, name, type}`, `type` ∈ `image` \| `collection`. Recurse with a `collection` identifier.
`get_image_info`	Dimensions + served capabilities of an image identifier.	JSON: `width`, `height`, `formats`, `qualities`, `maxWidth`/`maxHeight` — the machine-readable equivalent of the image's `info.json`.
`get_region`	Renders a region of an image.	An image the agent can see. Parameters follow the IIIF Image API 3.0 grammar (`region`: `full`\|`square`\|`x,y,w,h`\|`pct:…`; `size`: `max`\|`w,`\|`,h`\|`w,h`\|`!w,h`\|`pct:n`; plus `rotation`, `quality`, `format`). Omitted fields default to `full`/`max`/`0`/`default`/`jpg`.
`get_manifest`	Returns the IIIF Presentation document for an identifier — a stored manifest/collection served as-is, or one derived on the fly from a directory (images → a Manifest, one canvas each; sub-directories → a Collection).	The JSON document (Presentation 3.0).

A typical agent flow: browse to find a collection, browse into it to find an image identifier, then get_image_info / get_region on that identifier, or get_manifest on a directory identifier to get the structured document.

Resources¶

Manifests are also exposed as MCP resources — a URI-addressable, host-readable view of the same documents get_manifest returns. A resource template is advertised:

iiiris:///presentation/{identifier}

A host constructs a URI for any identifier (which may contain slashes, e.g. iiiris:///presentation/library/manuscript) and reads it to get the manifest as application/ld+json. Use browse to discover which identifiers exist. Resource reads are authorized exactly like the get_manifest tool.

get_region renders through the same pipeline the Image API uses, with the same size/area limits enforced — an MCP caller cannot request a render the HTTP API would reject.

Contracts¶

Read-only, stateless. The tools resolve, probe, render, and list; they add no state. The endpoint runs in the SDK's stateless mode (no session tracking).
Reuses IIIF resolution. Identifiers returned by browse are the same identifiers get_image_info / get_region accept — all go through the same hook + source resolution the Image API uses.
Honest capabilities. A source without listing support (e.g. plain HTTP) reports a browse error rather than an empty listing.

Not yet supported¶

Write tools (ingest, annotate) — align with the roadmap's stateful Phase 3 work.
stdio transport — iiiris is a networked server; only Streamable HTTP is offered.

Security¶

Off by default; enable deliberately. Treat /mcp as another public surface of the server.
MCP enforces the same IIIF Auth as the Image API. Every tool routes through the configured authorizer, using the credentials on the /mcp request. An MCP host authenticates by presenting its IIIF access token as a Bearer token (or the session cookie) on its connection to /mcp — the same token the Image API accepts. There is no separate MCP credential and no extra config; MCP rides the existing auth.
Without a valid credential, a gated identifier is denied (get_image_info / get_region / get_manifest return an access-denied error), and browse omits entries the caller can't reach.
With the zero-config default (no auth configured), nothing is gated.
Render limits apply. get_region is bounded by the same maxWidth/maxHeight/maxArea guards as the Image API.