Upload Center

Image upload manager with a file-browser UI, REST API, and MCP server for any AI agent.

Upload demo and product images, organize them in folders, copy public URLs (one per line or comma-separated for Excel), and let AI agents upload images programmatically.

Quick Start

1. Open the web app

Production:

https://uploads.craffo.com

Local Herd: https://uploads.test

Default web password: 2030 (change in index.php).

2. Generate an API key

Required for MCP and programmatic API access:

php -r "file_put_contents('.api-key', bin2hex(random_bytes(32)));"

Or set the environment variable UPLOAD_CENTER_API_KEY.

3. Connect your AI agent

Run ./bin/setup-mcp-config.sh or point your MCP client at /agent.php with your API key.

See Agent API for details.

Web UI

Log in and use the file browser to manage uploads.

Keyboard shortcuts

• Ctrl/Cmd + A — select all
• Ctrl/Cmd + C — copy selected URLs
• Delete — delete selected items

Authentication

All API endpoints support two auth methods:

Session (web UI)

Log in via the web interface. Requests use the PHP session cookie.

API key (MCP, scripts, curl)

X-API-Key: your-api-key-here

Or Bearer token:

Authorization: Bearer your-api-key-here

The key is read from UPLOAD_CENTER_API_KEY env var or the .api-key file in the project root.

HTTP API

All endpoints return JSON. Paths are relative to /uploads (e.g. products/banner.jpg).

GET list.php

List folders and images.

curl -H "X-API-Key: $(cat .api-key)" \
  "https://uploads.craffo.com/list.php?path=products"

POST upload.php

Upload images. Body: multipart/form-data

Max 8 MB per file. Types: jpg, jpeg, png, webp, gif.

curl -H "X-API-Key: $(cat .api-key)" \
  -F "files[]=@/path/to/image.jpg" \
  -F "path=products" \
  https://uploads.craffo.com/upload.php

POST mkdir.php

curl -H "X-API-Key: $(cat .api-key)" \
  -H "Content-Type: application/json" \
  -d '{"path":"products","name":"summer-sale"}' \
  https://uploads.craffo.com/mkdir.php

POST delete.php

curl -H "X-API-Key: $(cat .api-key)" \
  -H "Content-Type: application/json" \
  -d '{"paths":["products/old.jpg","products/archive"]}' \
  https://uploads.craffo.com/delete.php

POST clean.php

Empty a folder (all files and subfolders).

curl -H "X-API-Key: $(cat .api-key)" \
  -H "Content-Type: application/json" \
  -d '{"path":"products"}' \
  https://uploads.craffo.com/clean.php

Configuration

Uploaded files are stored as: {timestamp}_{random}_{name}.{ext}

Security

• Change the default web password before deploying
• Keep .api-key secret — never commit it
• Path traversal is blocked on all endpoints
• uploads/.htaccess denies script execution
• API key comparison uses timing-safe hash_equals()

Agent API (URL)

All AI agents connect via HTTP to a single URL. No local Node process or project path required.

Discover capabilities

curl -H "X-API-Key: $(cat .api-key)" \
  https://uploads.craffo.com/agent.php

Returns a manifest with all tools, endpoints, and auth info.

Call a tool (simple JSON)

curl -H "X-API-Key: $(cat .api-key)" \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_uploads","arguments":{"folder":""}}' \
  https://uploads.craffo.com/agent.php

Upload images (base64)

curl -H "X-API-Key: $(cat .api-key)" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "upload_images",
    "arguments": {
      "folder": "products",
      "files": [
        {
          "name": "photo.jpg",
          "content_base64": "'$(base64 -i photo.jpg)'"
        }
      ]
    }
  }' \
  https://uploads.craffo.com/agent.php

MCP JSON-RPC (for MCP clients)

curl -H "X-API-Key: $(cat .api-key)" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://uploads.craffo.com/agent.php

Connect any MCP client via URL

Use this config in Cursor, Claude Desktop, VS Code, or any MCP client that supports remote URL servers. Replace the API key with your value from .api-key:

{
  "mcpServers": {
    "upload-center": {
      "url": "https://uploads.craffo.com/agent.php",
      "headers": {
        "X-API-Key": "paste-your-api-key-here"
      }
    }
  }
}

MCP Tools

Five tools exposed to connected agents:

Common Workflows

Upload and return URLs

1. create_upload_folder (optional)
2. upload_images with file paths
3. get_upload_urls with desired format

Excel / comma-separated URLs

1. upload_images
2. get_upload_urls with format: "comma"

Path conventions

AI Agent Guide

Decision guide

Do's and don'ts

Troubleshooting