Phototology

@phototology/mcp

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

[npm version] [License: MIT] [MCP spec] [Node]

[Install in VS Code] [Install in VS Code Insiders] [Install in Cursor]

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.

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

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

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