phototology

@phototology/mcp

Persistent memory for visual intelligence. Analyze once. Remember forever.

Click an install button to add the MCP server in one step. You'll be prompted to fill in PHOTOTOLOGY_API_KEY after install. For other editors, see the Setup section below.

MCP server for Phototology, the visual-intelligence registry. Any MCP-speaking agent (Claude Code, Cursor, VS Code Copilot, Claude Desktop) calls Phototology as a tool. Photos are analyzed once, keyed by perceptual hash, then returned free forever to any future caller on the same account.

npx @phototology/mcp

The interactive wizard asks for your API key and writes the config for whichever editor you pick.

Without Phototology vs With Phototology

Without: every agent that needs to understand a photo pays a vision model from scratch. Same image, same question, full price every time.

With: the first call bills 1 credit per lens. Every subsequent call on that photo returns the cached lens result for free. The registry compounds with use.

When to reach for Phototology

Reach for it when:

• An agent needs the same photo understood more than once. The registry makes every re-read free.
• You want structured fields (dates, condition, text, location, and more) instead of freeform prose.
• Cost predictability matters. Every tool and every lens discloses its credit cost up front.

Look elsewhere when:

• You need live video or a streaming camera feed. Phototology analyzes still images.
• You need to identify a specific named person. Phototology describes people; it never matches identity.
• You want a model to chat about an image. Phototology returns structured data, not dialogue.

Phototology vs a stateless vision wrapper

Capability	Stateless vision wrapper	Phototology
Repeat calls on the same photo	Pays the vision model again every time	Cached free forever, keyed by perceptual hash
Memory across calls	None	Persistent registry (sha256 + pHash)
Output	Freeform text	Structured JSON, one field set per lens
Cost to the agent	Opaque	Per-tool, per-lens credit cost disclosed
Near-duplicate detection	None	Exact (sha256) and perceptual (pHash) matching

The persistent registry, the perceptual-hash dedup, and the free re-reads are the difference.

What Phototology does not do

Stated plainly, so an agent can route correctly:

• No identity recognition. The people lens reports physical observations and a head count, never a name or a face match.
• No checkout inside the MCP. purchase_credits returns a wallet deep-link. Stripe checkout needs a browser.
• No C2PA signing yet. enrich_photo writes EXIF, IPTC, and XMP. formats: ["c2pa"] is rejected.
• No remote endpoint yet. The server runs over stdio. A hosted transport is a follow-up.
• No local model. Every analyze call reaches the hosted Phototology API. An API key and a network connection are required.

7 tools at a glance

Tool	What it does	Cost
analyze_photo	Run AI vision against ONE image and return structured facts per lens. Accepts imageUrl, imageBase64, or imagePath.	1 credit per lens. Re-running cached lenses on the same photo: 0.
analyze_batch	Analyze 1 to 200 photos in a single call. Internally lookup-first per URL (20 in flight), then analyzes cache-miss photos with bounded concurrency (5 in flight, matching the API per-user cap). For thousands, loop in slices of 200. Accepts imageUrls, imagesBase64, or imagePaths (with glob support). Returns { summary, results }; pass dryRun: true to see what a batch would cost without spending.	1 credit per lens per non-cached photo. Cache hits free. A dry run is free.
lookup_photo	Check if a single photo has already been analyzed; return all cached lens results. Accepts sha256, pHash, imageUrl, imageBase64, or imagePath (cascade).	Free.
enrich_photo	Write cached lens output into a photo's EXIF/IPTC/XMP metadata so the structured intelligence travels with the file. Accepts imageUrl, imageBase64, or imagePath plus an optional outputPath that saves the enriched copy as a new file (the original is never written; an existing file is refused unless overwrite: true). Returns a small JPEG preview of the enriched photo. A photo carrying a valid content credential is left untouched: the analysis is saved beside it as <imagePath>.xmp (sidecarSavedTo), or returned as sidecar.xmp, with mode: 'sidecar', reason, credentials and a plain-words note. Pass breakCredentials: true to write a copy anyway.	5 credits per call.
list_lenses	Enumerate available lenses and stacks with descriptions and output fields.	Free.
get_credits	Read the account credit balance: total spendable credits and its dollar value usd, plus reserved in-flight holds when there are any.	Free.
purchase_credits	Return a wallet deep-link the user can open to buy more credits.	Free.

How they chain. Start free: lookup_photo for a single image, or get_credits before a batch. Analyze only the cache misses with analyze_photo (one image) or analyze_batch (2 or more). Bake the results into the file with enrich_photo. list_lenses and purchase_credits are free helpers you can call any time.

Resources

URI	What it serves
phototology://lenses	The lens and stack catalog, the same data list_lenses returns.
phototology://photo/{sha256}	One registry record: its hashes, the lenses already run on it, and their receipts. Free to read. A photo not in the registry reads as PHOTO_NOT_IN_REGISTRY.

analyze_photo, analyze_batch and lookup_photo link each photo they name to its phototology://photo/{sha256} resource.

Receipts

Analyze and lookup results carry receipts: signed records of which lenses ran on which photo, with which model, and when. Results also carry credentials when the API read the photo's content credential. To check a receipt, use verifyReceiptSignature (offline) or client.verifyReceipt (server-side, free) from @phototology/sdk.

Who gets receipts today. Only pt_test_ keys receive receipts right now. Those are signed by the published sandbox key, which never vouches for live data: they check your integration, not a photo. Production has no published live signing key yet, so until it is, a pt_live_ key receives receipts: [] with the warning RECEIPT_UNAVAILABLE on a fresh analyze, and with RECEIPT_NONE_STORED on a result served from the registry (no live receipt has been stored yet). The analysis and its billing are unaffected.

When receipts is empty on an analyze result, warnings names why (a fresh analyze whose lenses produced no output issues neither a receipt nor a warning):

Code	Meaning
RECEIPT_UNAVAILABLE	No receipt could be signed for this call: no live signing key is configured and published, or signing failed or timed out. The analysis itself is complete.
RECEIPT_NONE_STORED	The result came from the registry, and no stored receipt covers the lenses asked for (the analysis predates receipts or was issued without one).
RECEIPT_NOT_ISSUED_MULTI_IMAGE	The call sent more than one image; receipts are issued for single-image calls only.
RECEIPT_NOT_ISSUED_BESPOKE	The call used a custom extraction schema; those calls get no receipt.
RECEIPT_NOT_ISSUED_NO_ACCOUNT	The key is not linked to an account, so there is no registry record for a receipt to name.

analyze_photo results and analyzed analyze_batch rows carry these warnings. lookup_photo and batch rows served from the registry carry the photo's stored receipts and no receipt warning: an empty list there means no stored receipt covers that photo.

Credentials on enrich_photo. The credentials block on an enrich result describes the input photo, as read before the write. With breakCredentials: true, the written copy no longer carries a valid content credential, even when credentials reports one on the input.

Pricing

• 1 credit = $0.01 = one lens run on one photo. Stack five lenses on a photo = 5 credits = $0.05.
• 1,000 free credits when you sign up: granted when you verify your email. One-time, not recurring.
• Lookups, lens discovery, balance reads, and purchase links are always free.
• Cache hits cost zero. Re-running the same lens on the same photo returns the cached output for free. The registry keeps re-runs free across sessions.
• Bespoke schema extraction = 5 credits per image (plus 1 per additional stacked lens).
• Moderation is free and always-on. It's safety infrastructure, never billed.

Credit packs (all at $0.01/credit, no volume discount)

Pack	Credits	Price
Starter	1,000	$10
Pro	10,000	$100
Business	100,000	$1,000

First purchase doubles. Your first pack ever credits 2x. A Starter $10 buys 2,000 credits the first time. No subscriptions; pay-as-you-go via packs only.

Local files

All three image-accepting tools (analyze_photo, analyze_batch, lookup_photo) accept three input modes. Pick whichever fits how the photo arrived:

Input field	When to use
imageUrl	The photo is at a publicly-fetchable URL.
imagePath	The photo is on the user's local disk as seen by the machine running the MCP server (typically the user's laptop). Pass an absolute path (/Users/...) or ~/-prefixed (~/photos/...). The MCP reads the file, validates it, and forwards the bytes. Not for agent-sandbox paths (e.g. Claude's /mnt/user-data/uploads/...): that sandbox is invisible to a locally-installed MCP. For agent-sandboxed uploads, use imageBase64 (small images) or imageUrl (hostable images of any size).
imageBase64	You already have the image bytes in memory as a base64 string. Practical envelope: ~50-150KB JPEG / ~70-200K base64 chars. Above that, LLM-driven clients run out of output-token budget before the MCP receives the full payload (a 3.4MB JPEG produces ~4.57M chars). For larger images, prefer imageUrl or imagePath.

For batch: use imagePaths: string[] for local paths (supports globs like ~/vacation/*.jpg), imagesBase64: string[] for base64 arrays, and combine freely with imageUrls.

lookup_photo with imagePath / imageBase64 runs a transparent sha256→pHash cascade. It is always free, and checks both exact-bytes and perceptually-similar matches.

The registry matches in this order: sha256 (same bytes), then decoded pixels (same image, different metadata), then PDQ (a near-duplicate such as a re-encode, rotation or flip, within distance 31, for images with PDQ quality of at least 50), then pHash. Before any of that, lookup_photo tries the registry id that enrich_photo wrote into the file's IPTC Extension (RegistryID), so an enriched copy still finds its original record; a hit says matchedBy: "registryId". enrich_photo reports registryId in its result when it wrote one.

Per-image cap: 10MB raw. Batch cap: 200 inputs total per call. Supported formats: JPEG, PNG, GIF, WebP, AVIF, TIFF. HEIC/HEIF is refused with a conversion hint until the API can decode it.

Setup: pick your editor

Claude Code

Run this once in a terminal:

claude mcp add phototology --scope user -e PHOTOTOLOGY_API_KEY=pt_live_... -- npx -y @phototology/mcp

That writes the server into ~/.claude.json, so every project sees it. Use --scope project instead to write .mcp.json at the project root and share it with the repo. Both files take this shape if you edit them by hand:

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Cursor

.cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

VS Code Copilot

.vscode/mcp.json:

{
  "servers": {
    "phototology": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.phototology]
command = "npx"
args = ["-y", "@phototology/mcp"]

[mcp_servers.phototology.env]
PHOTOTOLOGY_API_KEY = "pt_live_..."

After editing the config, restart your editor. You should see 7 tools registered under phototology.

First 5 minutes

Try these prompts in order:

1. Discover. "Use the phototology MCP to show me what lenses are available." The agent calls list_lenses and shows you every available lens and stack.
2. Check your balance. "How many phototology credits do I have?" The agent calls get_credits and reports your spendable credit balance.
3. Cheap analyze. "Analyze this photo with just the dating lens: <url>." The agent picks lenses: ["dating"] and spends 1 credit instead of running the full catalog.
4. Free re-lookup. Repeat the same URL with a different question that the cached lens already answers. Zero credits.
5. Out of credits. Drain the pool, try another analyze. The agent receives a structured error with a wallet deep-link and surfaces it cleanly.

Companion skills

Five optional skills ship inside the package under node_modules/@phototology/mcp/skills/. Copy any of them into your Claude skills directory (~/.claude/skills/<skill-name>/) to install:

• phototology:lookup-first: always check the registry before spending credits (single-photo).
• phototology:check-credits: pre-flight balance read before a big batch.
• phototology:smart-stack: smart-pick the cheapest lens subset for a specific question.
• phototology:photo-shared: activate whenever the user shares, attaches, drops, or references an image. Routes the photo through Phototology for the cheapest accurate answer.
• phototology:batch-analyze: any job with 2 or more photos. Calls analyze_batch instead of looping analyze_photo. Looks up first, analyzes only the misses, surfaces credit savings.

When installed, the agent invokes them when context matches.

Optional: auto-trigger on image attachment (Claude Code)

If you want Claude Code to automatically hint at Phototology the moment you attach an image (no model discretion required), add this hook to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "image",
        "command": "echo 'User shared an image. Consider phototology:photo-shared to route it through the registry-first analysis path.'"
      }
    ]
  }
}

The hook injects a system hint on every prompt containing an image, nudging the model toward the phototology:photo-shared skill before it picks anything else. Skip the hook if you prefer to let the model decide on its own.

Lens reference

Lens	Owned output fields
dating	estimatedDate, techAnchors, temporalMarkers, title, genre, caption, dateAnchors, season, holiday, event, visibleDates, reproduction
people	physicalObservations, collectionDynamics, peopleCount
location	location
atmosphere	atmosphere, emotions, warmCaption, semanticDescription
entities	entities
accessibility	accessibility
photo-quality	quality, visualFaults, rotation, documentClassification, scan
text-content	textContent
composition	composition
moderation	moderation
describe	describe
condition	condition
authenticity	authenticity
color-palette	colorPalette
automobile	automobile
vehicle-condition	overallCondition, componentGrades, observations, accidentIndicators, photoQuality, missingViews, vehicleContext, photos, sellerSummary

Pass any of these as lenses: [...] on analyze_photo, or use a stack (full-analysis, quick-scan, automobile, claims, property, ecommerce, memorial, vehicle-condition) to bundle several. The stack enum on the tool schema is the authoritative list; new lenses appear here automatically on publish.

Note on naming. The previous tool name was list_modules and the previous arg names were modules / preset. The current names are list_lenses / lenses / stack. The old names still work as deprecated aliases on analyze_photo during the rename. Prefer the new names in new code.

Delta billing

Phototology remembers every photo per account, keyed by perceptual hash. The second call on the same image bills zero credits for any lens that was already run. Only new lenses hit the LLM. Pass refresh: true to bypass the cache and re-run.

Environment variables

Variable	Required	Description
PHOTOTOLOGY_API_KEY	Yes	Your API key (pt_live_... or pt_test_...). Sign up for an account key at https://phototology.com/signup.
PHOTOTOLOGY_BASE_URL	No	API base URL. Default: https://api.phototology.com.
PHOTOTOLOGY_MCP_NO_TELEMETRY	No	Set to 1 to disable anonymous client-discovery telemetry (see below).
DO_NOT_TRACK	No	Set to 1 to disable telemetry. Same effect as PHOTOTOLOGY_MCP_NO_TELEMETRY; it follows the cross-tool convention many CLIs honor.
PHOTOTOLOGY_MCP_ALLOWED_DIRS	No	Folders the server may read photos from and write enriched copies to, separated by : (; on Windows), for example /Users/me/Pictures:/Volumes/Archive. Unset means any local path. Paths are checked after symlinks are resolved, so a link inside an allowed folder that points elsewhere is refused with PATH_OUTSIDE_ALLOWED_DIRS.

Keys starting with pt_test_ use the test sandbox (instant responses, zero cost, golden fixtures). The sandbox allows 2 requests a minute and 10 a day per IP; past that, tools return a RATE_LIMITED error with retryAfterSeconds instead of waiting. Every tool error from the API starts with one line of JSON (code, retryable, and fields such as retryAfterSeconds or actionUrl), followed by a sentence; error results carry no structuredContent. A sandbox key cannot read the registry or a balance, or write metadata into a photo: lookup_photo, get_credits and enrich_photo return a SANDBOX_KEY error. Sign up for an account key at https://phototology.com/signup for those.

Anonymous telemetry

When the MCP server completes the initialize handshake with your editor, it reports the editor's stated name + version (e.g. claude-desktop 0.7.0, cursor 0.42) plus the MCP package version to api.phototology.com so we can see which clients are connecting. After each tool call it sends one event with the tool name, whether the call succeeded, how long it took, an error code if it failed, and counts: credits charged, lenses run, photos submitted, cache hits, and whether an analyze_photo call was a full cache hit. This is the same domain your tool calls already go through. No third-party SDK is bundled, and your API key is the only credential used. No image content, file paths, prompts, conversation text, or tool inputs/outputs are sent.

Set PHOTOTOLOGY_MCP_NO_TELEMETRY=1 or DO_NOT_TRACK=1 in the same env block as PHOTOTOLOGY_API_KEY to disable. Telemetry is also off whenever the process runs with NODE_ENV=test.

Security model

The full policy is in SECURITY.md. In short:

• What it reads. Only the files you name, by absolute path (or ~/ path). When PHOTOTOLOGY_MCP_ALLOWED_DIRS is set, only files inside those folders, checked after symlinks are resolved. enrich_photo writes only to the outputPath you pass, or to <imagePath>.xmp beside a photo that carries a valid content credential, and inside those folders when they are set.
• What it sends. Image bytes (or the URL or hash you passed) to api.phototology.com, plus the telemetry payload described under Anonymous telemetry.
• What it never sends. File paths, tool inputs or outputs in telemetry, or your conversation text.
• What is not a boundary. Tool annotations such as readOnlyHint are hints to your editor, not enforcement. The server itself runs with your user's permissions and is not a sandbox. Keep your editor's tool confirmations on.
• Reporting a vulnerability. Email [email protected]. Please do not open a public issue.

FAQ

Why does analyze_photo accept both lenses and modules? The brand name was unified from "module" to "lens" in 2026-04. Both names are accepted on the MCP surface during the rename; the SDK still uses modules. Prefer lenses in new code.

Why is moderation never billed? Moderation is safety infrastructure, not a feature you opt into. CSAM + illegal-content detection runs on every analyze. Treating it as a price line item would create perverse incentives.

How is get_credits different from lookup_photo? get_credits reads your account balance. lookup_photo checks whether a specific image has been analyzed before. Both are free; they answer different questions.

Why is purchase_credits a "deep-link" instead of completing checkout? Stripe checkout requires a browser. The MCP cannot complete payment; the user must open the URL the tool returns.

Links

• TypeScript SDK: npm install @phototology/sdk
• API Documentation
• OpenAPI Spec
• GitHub

License

MIT