模型上下文协议 (MCP) 集成

PreviewFile.dev 提供 MCP 服务器，使 AI 代理和助手能够以编程方式上传附件并生成安全的预览 URL。这允许与 Claude、Cursor、Cherry Studio、Windsurf、Chatbox AI 等 MCP 兼容客户端无缝集成。

快速开始

MCP 端点

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

传输协议: HTTP 流式传输 (MCP 规范修订版 2025-06-18)

认证方式

所有 MCP 请求都需要使用 API 密钥进行认证。您可以在 控制台设置 获取 API 密钥。

支持的认证方式

配置示例

{
  "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"
      }
    }
  }
}

可用工具

PreviewFile MCP 服务器提供 2 个工具 用于文件上传和预览生成：

工具概览

previewfile_upload_from_url

通过提供 URL 上传文件。服务器获取文件并创建预览会话。这是从现有文件创建预览链接的主要方法。

参数：

响应示例：

{
  "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

请求预签名 URL 以将文件直接上传到存储。当您需要上传无法通过 URL 访问的文件时使用。

参数：

响应示例：

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

收到预签名 URL 后，使用 HTTP PUT 将文件直接上传到返回的 uploadUrl。

建议提示词

以下是一些帮助您开始使用 PreviewFile MCP 服务器的自然语言提示词：

URL 转预览提示词

"将这个 S3 URL 转换为安全预览链接：https://bucket.s3.amazonaws.com/doc.pdf"

"为这个文件 URL 创建一个 2 小时有效期的预览"

"为这个外部文档生成带水印的预览链接"

"为这份合同 URL 创建一个查看后即过期的一次性预览链接"

"禁止下载方式上传这个 URL 的文件：https://example.com/report.pdf"

直接上传提示词

"获取一个预签名 URL，以便我上传大型视频文件"

"我需要上传一个 50MB 的演示文稿 - 给我一个上传 URL"

使用场景

1. AI 辅助文档分享

让您的 AI 编程助手在讨论文档时自动生成安全预览链接：

用户："分享这份 S3 文档给团队，不要暴露我们的存储桶 URL"
AI：*使用 previewfile_upload_from_url 获取并生成安全链接*
    "这是您的安全预览链接：https://previewfile.dev/p/abc123
     链接 1 小时后过期。原始 URL 已隐藏。"

2. 安全的外部文件分享

将任何可访问的 URL 转换为安全的限时预览：

用户："为这份客户报告创建预览链接：https://pdfobject.com/pdf/sample.pdf"
AI：*使用 previewfile_upload_from_url 并设置 noDownload=true*
    "预览链接已创建：https://previewfile.dev/p/xyz789
     下载已禁用。1 小时后过期。"

3. 带水印的文档分发

分享带有追踪水印的机密文档：

用户："分享这份合同给供应商，但要添加水印"
AI：*使用 previewfile_upload_from_url 并设置 watermark 参数*
    "已创建带'供应商审阅'水印的预览链接：https://previewfile.dev/p/abc456
     水印将显示在所有页面上。"

4. 一次性安全链接

为敏感内容创建自毁预览链接：

用户："为这份机密文档创建一次性链接"
AI：*使用 previewfile_upload_from_url 并设置 oneTime=true*
    "一次性预览链接已创建：https://previewfile.dev/p/wire123
     链接在首次访问后立即过期。"

预签名上传工作流

对于无法通过 URL 访问的文件，使用预签名上传工作流：

{
  "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

安全功能

MCP 服务器继承了所有 PreviewFile 安全功能：

错误处理

MCP 服务器返回带有清晰消息的结构化错误：

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

常见错误

速率限制

MCP 请求计入您的 API 速率限制：

故障排除

连接问题

问题：AI 客户端无法连接到 MCP 服务器

解决方案：

1. 验证您的 API 密钥正确且有效
2. 检查端点 URL：https://previewfile.dev/api/v1/mcp
3. 确保您的客户端支持 HTTP 流式传输
4. 检查网络/防火墙限制

上传失败

问题：文件上传失败或超时

解决方案：

1. 对于大文件，使用预签名上传工作流
2. 验证 base64 编码正确（无 data URL 前缀）
3. 检查文件大小是否在 500MB 限制内
4. 确保 MIME 类型与实际文件内容匹配

认证错误

问题："Authentication required" 错误

解决方案：

1. 从 控制台设置 生成新的 API 密钥
2. 验证密钥传递正确：
   • Bearer 令牌：Authorization: Bearer <key>
   • 请求头：x-api-key: <key>
3. 检查密钥是否已被撤销

常见问题

不使用 API 密钥可以使用 MCP 吗？

不可以，所有 MCP 操作都需要认证。请从 控制台设置 获取您的 API 密钥。

最大文件大小是多少？

每个文件 500MB。

上传的文件是永久的吗？

不是，所有文件根据配置的 TTL 自动过期。最大保留时间取决于您的套餐。

可以通过 MCP 列出所有预览吗？

目前，请使用 控制台 或 REST API 列出预览。MCP 专注于上传和单个预览操作。

文件去重是自动的吗？

是的，具有相同 SHA-256 哈希的文件只存储一次，节省存储和带宽。

后续步骤

• 📖 查看 REST API 文档 了解更多端点
• 🔒 阅读 安全策略 了解数据保护详情
• 💰 访问 定价页面 比较套餐
• 🎨 查看 支持的格式 了解文件兼容性

需要帮助？ 联系我们：[email protected]