Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

MCP server

PixelVault runs two Model Context Protocol servers, so any MCP-capable agent (Claude, Cursor, and others) can host media and manage custom domains: a remote one for URLs, attachments, and base64 images, and a local one for media files on disk. Start with the hosted server: there is nothing to install, it works with remote clients, and it gets new tools first. Add the local one when your agent needs filesystem paths (compare the two).

Hosted server

The remote server is hosted on Cloudflare's edge at:

https://mcp.pixelvault.dev/mcp   (transport: streamable-http)

Authenticate by sending your API key as a Bearer token. Add it to Claude Code with:

claude mcp add --transport http pixelvault https://mcp.pixelvault.dev/mcp \
  --header "Authorization: Bearer $PIXELVAULT_API_KEY"

Or configure any client that supports the streamableHttp transport:

{
  "mcpServers": {
    "pixelvault": {
      "type": "streamable-http",
      "url": "https://mcp.pixelvault.dev/mcp",
      "headers": { "Authorization": "Bearer pv_live_xxxxxxxx" }
    }
  }
}

OAuth (for ChatGPT apps, Claude connectors and other OAuth clients): connect to https://mcp.pixelvault.dev/mcp/oauth instead — no key to paste. You authorize through a short email-code consent screen and PixelVault mints a per-user key behind the scenes. The /mcp endpoint above (API key) stays available for existing clients. Step-by-step for Claude: Upload images from Claude.

Tools

The hosted server exposes these tools:

ToolDescription
create_upload_urlPrepare a 10-minute image upload URL and curl command for a local shell file
upload_imageUpload an image attachment, base64 data, or public source_url; supports TTL, privacy, retry safety, metadata, and AI description
upload_videoUpload an MP4 attachment or import a public source_url; supports private delivery, TTL, metadata, folder, collection, and retry safety
get_videoGet one video's metadata, lifecycle fields, asynchronous job IDs/status, and available artifacts
list_videosList videos with pagination and optional folder, collection, or metadata filters
update_videoReplace or clear a video's metadata, folder, or collection membership
sign_video_urlMint expiry-matched signed URLs for a private video's original and every available artifact
delete_videoPermanently delete a video and all of its derived artifacts
optimize_videoCreate a separate social-ready H.264/AAC fast-start copy; optionally wait with a bounded timeout
enrich_videoGenerate transcript and storyboard artifacts; optionally wait with a bounded timeout or resume with get_video
upload_audioUpload an MP3/WAV/M4A/OGG attachment or securely import source_url; validates bytes and supports privacy, TTL, organization, metadata, and retry safety
enrich_audioStart or resume text/WebVTT/timestamped-JSON transcription; optionally wait with a bounded timeout or resume with get_audio
get_audioGet one audio original, transcription job state and available transcript URLs, detected media metadata, privacy, expiry, and organization
list_audioList audio with pagination and folder, collection, or metadata filters
update_audioReplace or clear audio metadata, folder, or collection membership
sign_audio_urlMint fresh expiry-matched URLs for a private audio original and available transcripts
delete_audioPermanently delete an audio original, transcripts, and active job state
upload_batchUpload 1–50 images in one collection, with partial-failure results
generate_imageGenerate and host an image from a prompt using monthly generation credits
edit_imageEdit a hosted image from a prompt and store the result as a new image
sign_urlMint a time-limited signed URL for a private image
transform_imageBuild an on-the-fly image transform URL
get_imageGet metadata and the CDN URL for one image
list_imagesList images, filter by metadata or AI tag, or search AI descriptions
update_image_metadataReplace or clear an image's custom metadata
list_image_tagsList AI-generated image tags and their usage counts
describe_imageStart AI alt text, caption, OCR, and tags for an existing image
delete_imagePermanently delete one image
list_collectionsList collections, optionally filtered by type and name
get_collectionGet one collection and its images
close_collectionClose a collection; a closed ci_build becomes eligible for cleanup
list_custom_domainsList custom domains, DNS records, readiness, and account plan capacity
create_custom_domainAttach a customer-owned hostname to the active project
refresh_custom_domainRe-check DNS and certificate state after records change
delete_custom_domainRemove a custom domain; canonical PixelVault URLs keep working
list_webhooksList signed callback endpoints and subscriptions
create_webhookCreate a callback endpoint and return its signing secret once
update_webhookUpdate a callback URL, event subscriptions, description, or active state
delete_webhookDelete a callback endpoint and its delivery log
rotate_webhook_secretInvalidate and replace a callback signing secret
list_webhook_deliveriesInspect recent callback delivery attempts and outcomes
get_usageShow plan, usage, and remaining quota
upgrade_planReturn a Stripe Checkout URL for the account owner; API-key endpoint only
manage_billingReturn a Stripe billing-portal URL for the account owner; API-key endpoint only
rescue_imgurFind hotlinked Imgur images on a page and return rescue URLs; no API key required

Long-running tools (optimize_video, enrich_video, enrich_audio) follow the same pending/complete pattern as the REST API; see Async jobs.

Hosted or local?

Hosted (mcp.pixelvault.dev)Local (local-mcp)
InstallNone, just a URLnpx, needs Node
Upload a file from disk by pathNo (host attachment, base64 image, or source_url)Yes; bytes never enter model context
Works with remote clients (ChatGPT, web apps)YesNo, it must run on your machine
AuthAPI key or OAuth (no key to paste)API key or ~/.pixelvault/config.json
ToolsComplete runtime inventory listed aboveImage, video, audio, and custom-domain tools

Rule of thumb: use the hosted server by default, and add the local one next to it if your agent uploads files from disk. They don't conflict.

Local MCP server (upload by file path)

Local MCP 0.8.0 reads image, video, and audio files directly from disk and exposes the same custom-domain management operations. Use the hosted MCP when the client cannot run a local process; use the local server when an agent must read a filesystem path without sending its bytes through model context.

claude mcp add pixelvault-local \
  --env PIXELVAULT_API_KEY="$PIXELVAULT_API_KEY" \
  -- npx -y @pixelvault-dev/local-mcp

Or configure it directly:

{
  "mcpServers": {
    "pixelvault-local": {
      "command": "npx",
      "args": ["-y", "@pixelvault-dev/local-mcp"],
      "env": { "PIXELVAULT_API_KEY": "pv_live_xxxxxxxx" }
    }
  }
}

Upload tools accept a filesystem path, public source_url, or supported inline data. Media responses include optional branded_url when the active project has a ready custom domain. The server reads PIXELVAULT_API_KEY or ~/.pixelvault/config.json, the same as the CLI. Source is on GitHub (MIT); published as @pixelvault-dev/local-mcp.

Next steps