MCP Integration

PicFast ships a Model Context Protocol (MCP) server that lets AI agents — Claude, Cursor, VS Code Copilot, and others — interact with your image hosting platform directly. Upload images from local files, browse your library, and manage uploads, all through a standardized protocol.

What is MCP?

The Model Context Protocol is an open standard that enables AI applications to interact with external tools and data sources. PicFast's MCP server exposes your image hosting as a set of tools and resources that any MCP-compatible client can consume.

Installation

The MCP server is published as @picfast/mcp on npm. No global install required — run it directly with npx:

npx @picfast/mcp

Configuration

Configure the MCP server in your client's settings. Two environment variables control behavior:

Variable	Required	Description
`PICFAST_BASE_URL`	Yes	Your PicFast server URL, e.g. `https://picfast.example.com`
`PICFAST_API_TOKEN`	No	API token for authenticated operations. Create one in the PicFast console (tokens start with `img_`). Omit for guest upload only.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "picfast": {
      "command": "npx",
      "args": ["-y", "@picfast/mcp"],
      "env": {
        "PICFAST_BASE_URL": "https://picfast.example.com",
        "PICFAST_API_TOKEN": "img_xxxxxxxx"
      }
    }
  }
}

Cursor / VS Code

Same configuration format. Add it in the MCP settings panel under Settings → MCP.

Tools

Tool	Auth Required	Description
`upload_image`	No	Upload an image from a local file path. Works in guest mode without a token.
`list_images`	Yes	List your uploaded images with pagination support.
`get_image`	Yes	Retrieve image details including all share link formats (URL, Markdown, HTML, BBCode).
`delete_image`	Yes	Delete an image by its key.
`get_usage_stats`	Yes	Check your current storage quota, usage, and image count.

Upload response format

A successful upload_image call returns a JSON response with these fields:

{
  "key": "abc123",
  "url": "https://picfast.example.com/i/abc123.png",
  "markdown": "![](https://picfast.example.com/i/abc123.png)",
  "html": "<img src=\"https://picfast.example.com/i/abc123.png\" />",
  "bbcode": "[img]https://picfast.example.com/i/abc123.png[/img]",
  "mimetype": "image/png",
  "original_size": 204800,
  "stored_size": 196500,
  "processed": true
}

Resources

MCP clients can also read these resource URIs for structured data access:

URI	Auth Required	Description
`picfast://user/profile`	Yes	Current user profile information
`picfast://images/{key}`	Yes	Image metadata and links for a specific image

Guest mode

When no PICFAST_API_TOKEN is set, the MCP server operates in guest mode. Only upload_image is available. Guest upload must be enabled on your PicFast instance (admin settings → allow guest upload). Authenticated tools will return an error if called without a token.

Error handling

All tool errors return a consistent JSON structure:

{"error": {"code": "UPLOAD_FAILED", "message": "The upload could not be completed."}}

Error codes include: UNAUTHORIZED, FORBIDDEN_SCOPE, INVALID_IMAGE_DATA, UPLOAD_FAILED, IMAGE_NOT_FOUND, INTERNAL_ERROR.

License

The MCP server is MIT-licensed. The npm package is @picfast/mcp.