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:
| Tool | Description |
|---|---|
create_upload_url | Prepare a 10-minute image upload URL and curl command for a local shell file |
upload_image | Upload an image attachment, base64 data, or public source_url; supports TTL, privacy, retry safety, metadata, and AI description |
upload_video | Upload an MP4 attachment or import a public source_url; supports private delivery, TTL, metadata, folder, collection, and retry safety |
get_video | Get one video's metadata, lifecycle fields, asynchronous job IDs/status, and available artifacts |
list_videos | List videos with pagination and optional folder, collection, or metadata filters |
update_video | Replace or clear a video's metadata, folder, or collection membership |
sign_video_url | Mint expiry-matched signed URLs for a private video's original and every available artifact |
delete_video | Permanently delete a video and all of its derived artifacts |
optimize_video | Create a separate social-ready H.264/AAC fast-start copy; optionally wait with a bounded timeout |
enrich_video | Generate transcript and storyboard artifacts; optionally wait with a bounded timeout or resume with get_video |
upload_audio | Upload an MP3/WAV/M4A/OGG attachment or securely import source_url; validates bytes and supports privacy, TTL, organization, metadata, and retry safety |
enrich_audio | Start or resume text/WebVTT/timestamped-JSON transcription; optionally wait with a bounded timeout or resume with get_audio |
get_audio | Get one audio original, transcription job state and available transcript URLs, detected media metadata, privacy, expiry, and organization |
list_audio | List audio with pagination and folder, collection, or metadata filters |
update_audio | Replace or clear audio metadata, folder, or collection membership |
sign_audio_url | Mint fresh expiry-matched URLs for a private audio original and available transcripts |
delete_audio | Permanently delete an audio original, transcripts, and active job state |
upload_batch | Upload 1–50 images in one collection, with partial-failure results |
generate_image | Generate and host an image from a prompt using monthly generation credits |
edit_image | Edit a hosted image from a prompt and store the result as a new image |
sign_url | Mint a time-limited signed URL for a private image |
transform_image | Build an on-the-fly image transform URL |
get_image | Get metadata and the CDN URL for one image |
list_images | List images, filter by metadata or AI tag, or search AI descriptions |
update_image_metadata | Replace or clear an image's custom metadata |
list_image_tags | List AI-generated image tags and their usage counts |
describe_image | Start AI alt text, caption, OCR, and tags for an existing image |
delete_image | Permanently delete one image |
list_collections | List collections, optionally filtered by type and name |
get_collection | Get one collection and its images |
close_collection | Close a collection; a closed ci_build becomes eligible for cleanup |
list_custom_domains | List custom domains, DNS records, readiness, and account plan capacity |
create_custom_domain | Attach a customer-owned hostname to the active project |
refresh_custom_domain | Re-check DNS and certificate state after records change |
delete_custom_domain | Remove a custom domain; canonical PixelVault URLs keep working |
list_webhooks | List signed callback endpoints and subscriptions |
create_webhook | Create a callback endpoint and return its signing secret once |
update_webhook | Update a callback URL, event subscriptions, description, or active state |
delete_webhook | Delete a callback endpoint and its delivery log |
rotate_webhook_secret | Invalidate and replace a callback signing secret |
list_webhook_deliveries | Inspect recent callback delivery attempts and outcomes |
get_usage | Show plan, usage, and remaining quota |
upgrade_plan | Return a Stripe Checkout URL for the account owner; API-key endpoint only |
manage_billing | Return a Stripe billing-portal URL for the account owner; API-key endpoint only |
rescue_imgur | Find 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) | |
|---|---|---|
| Install | None, just a URL | npx, needs Node |
Upload a file from disk by path | No (host attachment, base64 image, or source_url) | Yes; bytes never enter model context |
| Works with remote clients (ChatGPT, web apps) | Yes | No, it must run on your machine |
| Auth | API key or OAuth (no key to paste) | API key or ~/.pixelvault/config.json |
| Tools | Complete runtime inventory listed above | Image, 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
- Upload images from Claude with the OAuth connector.
- ChatGPT Custom GPT via an OpenAPI action.
- Agent discovery endpoints that advertise the server.