Model Context Protocol (MCP) Integration

PreviewFile.dev provides an MCP server that enables AI agents and assistants to upload attachments and generate secure preview URLs programmatically. This allows seamless integration with AI coding assistants like Claude, Cursor, Windsurf, Chatbox AI, and other MCP-compatible clients.

Quick Start

MCP Endpoint

https://previewfile.dev/api/v1/mcp

Transport: HTTP Streamable Transport (MCP spec revision 2025-06-18)

Authentication

All MCP requests require authentication using an API key. You can obtain your API key from the Dashboard Settings.

Supported Authentication Methods

Configuration Examples

{
  "mcpServers": {
    "previewfile": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-client-http",
        "https://previewfile.dev/api/v1/mcp"
      ],
      "env": {
        "MCP_BEARER_TOKEN": "your-api-key-here"
      }
    }
  }
}

Available Tools

The PreviewFile MCP server exposes 2 tools for file upload and preview generation:

Tool Overview

previewfile_upload_from_url

Upload a file by providing a URL. The server fetches the file and creates a preview session. This is the primary method for creating preview links from existing files.

Parameters:

Example Response:

{
  "shortUrl": "a1b2c3d4",
  "previewUrl": "https://previewfile.dev/p/a1b2c3d4",
  "expireAt": "2026-01-28T10:30:00Z",
  "status": "READY",
  "fileName": "report.pdf",
  "fileSize": 245678,
  "mimeType": "application/pdf"
}

previewfile_request_upload_url

Request a presigned URL for uploading files directly to storage. Use this when you need to upload files that aren't accessible via URL.

Parameters:

Example Response:

{
  "uploadUrl": "https://storage.previewfile.dev/upload/...",
  "tempKey": "tmp/space123/abc123.pdf",
  "expiresIn": 3600
}

After receiving the presigned URL, upload your file directly using HTTP PUT to the returned uploadUrl.

Suggested Prompts

Here are some natural language prompts to help you get started with the PreviewFile MCP server:

URL to Preview Prompts

"Turn this S3 URL into a secure preview link: https://bucket.s3.amazonaws.com/doc.pdf"

"Create a preview for this file URL with 2-hour expiration"

"Generate a watermarked preview link for this external document"

"Create a one-time preview link for this contract URL that expires after viewing"

"Upload this file from URL with download disabled: https://example.com/report.pdf"

Direct Upload Prompts

"Get a presigned URL so I can upload a large video file"

"I need to upload a 50MB presentation - give me an upload URL"

Use Cases

1. AI-Assisted Document Sharing

Enable your AI coding assistant to automatically generate secure preview links when discussing documents:

User: "Share this S3 document with the team without exposing our bucket URL"
AI: *Uses previewfile_upload_from_url to fetch and generate a secure link*
    "Here's your secure preview link: https://previewfile.dev/p/abc123
     Link expires in 1 hour. Original URL is hidden."

2. Secure External File Sharing

Convert any accessible URL into a secure, time-limited preview:

User: "Create a preview link for this client report: https://pdfobject.com/pdf/sample.pdf"
AI: *Uses previewfile_upload_from_url with noDownload=true*
    "Preview link created: https://previewfile.dev/p/xyz789
     Download is disabled. Expires in 1 hour."

3. Watermarked Document Distribution

Share confidential documents with tracking watermarks:

User: "Share this contract with the vendor but add a watermark"
AI: *Uses previewfile_upload_from_url with watermark parameter*
    "Preview link created with 'Vendor Review' watermark: https://previewfile.dev/p/abc456
     The watermark will appear on all pages."

4. One-Time Secure Links

Create self-destructing preview links for sensitive content:

User: "Create a one-time link for this confidential document"
AI: *Uses previewfile_upload_from_url with oneTime=true*
    "One-time preview link created: https://previewfile.dev/p/wire123
     Link will expire immediately after first access."

Presigned Upload Workflow

For files that aren't accessible via URL, use the presigned upload workflow:

{
  "fileName": "large-video.mp4",
  "mimeType": "video/mp4",
  "sizeBytes": 52428800,
  "fileHash": "a1b2c3d4e5f6..."
}

curl -X PUT "${uploadUrl}" \
  -H "Content-Type: video/mp4" \
  --data-binary @large-video.mp4

Security Features

The MCP server inherits all PreviewFile security capabilities:

Error Handling

The MCP server returns structured errors with clear messages:

{
  "error": "TTL exceeds plan limit. Maximum allowed: 1440 minutes."
}

Common Errors

Rate Limits

MCP requests count against your API rate limits:

Troubleshooting

Connection Issues

Problem: AI client cannot connect to MCP server

Solutions:

1. Verify your API key is correct and active
2. Check the endpoint URL: https://previewfile.dev/api/v1/mcp
3. Ensure your client supports HTTP Streamable transport
4. Check for network/firewall restrictions

Upload Failures

Problem: File upload fails or times out

Solutions:

1. For large files, use the presigned upload workflow
2. Verify the base64 encoding is correct (no data URL prefix)
3. Check file size is under 500MB limit
4. Ensure MIME type matches the actual file content

Authentication Errors

Problem: "Authentication required" error

Solutions:

1. Generate a new API key from Dashboard Settings
2. Verify the key is passed correctly:
   • Bearer token: Authorization: Bearer <key>
   • Header: x-api-key: <key>
3. Check the key hasn't been revoked

FAQ

Can I use MCP without an API key?

No, authentication is required for all MCP operations. Get your API key from the Dashboard Settings.

What's the maximum file size?

500MB per file.

Are uploaded files permanent?

No, all files automatically expire based on the configured TTL. Maximum retention depends on your plan.

Can I list all my previews via MCP?

Currently, use the Dashboard or REST API for listing previews. MCP focuses on upload and single-preview operations.

Is file deduplication automatic?

Yes, files with identical SHA-256 hashes are stored once, saving storage and bandwidth.

Next Steps

• 📖 View REST API Documentation for additional endpoints
• 🔒 Read Security Policies for data protection details
• 💰 Visit Pricing Page for plan comparisons
• 🎨 Check Supported Formats for file compatibility

Need Help? Contact us: [email protected]