Phototology MCP

@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

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

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

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):

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)

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:

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

`look