Documentation
Back to Dashboard

Raycast Quick Upload

Copy a screenshot, hit a hotkey, get a public URL and asset_id on your clipboard. Pair with Claude + the BlackOps MCP to attach images to posts, tweets, and threads without leaving the keyboard.

The flow

  1. 1. Copy any image (screenshot, paste, drag from Finder).
  2. 2. Trigger Quick Upload Image in Raycast (recommended hotkey: ⌘⇧U).
  3. 3. A two-line payload lands on your clipboard:
    asset_id=e89cf199-ef4a-428e-893d-a7be8c4faade
url=https://.../site-assets/.../image.png
  4. 4. Paste it into Claude. The MCP attach_media_to_post / attach_media_to_tweet / attach_media_to_thread / attach_media_to_linkedin_post tools take the asset_id directly.

Why this exists

The MCP upload_media tool is URL-only — it fetches a publicly hosted URL into your media library. That works fine for assets already on the web, but a clipboard screenshot has no URL yet.

The Raycast command POSTs the bytes to POST /api/media/direct-upload, which:

  • Authenticates with your existing extension API token (Bearer auth)
  • Sniffs the content type from the bytes (no client-trust)
  • Stores the image in the canonical media bucket
  • Generates alt text server-side via Claude Haiku
  • Inserts a row into image_assets so it shows up in your media library
  • Returns the asset_id + public URL in one round trip

Setup

1

Install the extension

The Quick Upload command lives inside the idea-vault Raycast extension (alongside Capture Idea). Clone the repo and run:

cd raycast-idea-vault
npm install
npm run dev

npm run dev registers the extension with your local Raycast app. Once registered, you can stop the watcher — the command stays installed.

2

Configure preferences

In Raycast: Extensions → Idea Vault → Configure Command.

  • API URL: https://blackopscenter.com
  • API Token: your boc_ext_… token (generate at Settings → Integrations; the same token powers Capture Idea and the Chrome extension).
3

Bind a hotkey

In Raycast settings, give Quick Upload Image a global shortcut. Recommended: ⌘⇧U.

Endpoint reference

POST /api/media/direct-upload is also callable directly from any HTTP client (iOS share-sheet, scripts, etc.).

Request

POST /api/media/direct-upload
Authorization: Bearer <boc_ext_…>
Content-Type: multipart/form-data

file: <binary>           # required
filename_hint: <string>  # optional
kind: <string>           # optional, defaults to 'mcp-upload'
title: <string>          # optional

Response (200)

{
  "asset_id": "uuid",
  "url": "https://.../image.png",
  "filename": "image-1234-abc.png",
  "alt_text": "Server-generated alt text...",
  "content_type": "image/png",
  "size_bytes": 482910,
  "site_id": "uuid",
  "kind": "mcp-upload",
  "created_at": "2026-05-09T...",
  "thumbnail_url": "https://...",
  "dimensions": { "width": 1920, "height": 1080 }
}

Limits & errors

  • Max body size: 50 MB
  • Allowed types: jpeg, png, webp, gif, mp4, webm, quicktime (sniffed from magic bytes)
  • 401 — missing/invalid token
  • 403 — token has no associated site
  • 413 — body exceeds 50 MB
  • 415 — unsupported / mismatched content type
  • 500 — storage or DB failure

Test from the terminal

curl -X POST https://blackopscenter.com/api/media/direct-upload \
  -H "Authorization: Bearer $BOC_EXT_TOKEN" \
  -F "file=@/path/to/screenshot.png"

Relationship to upload_media

upload_media (MCP)

URL-only. Pass file_url.

Use when an asset is already publicly hosted somewhere (CDN, GitHub, etc.).

/api/media/direct-upload (REST)

Bytes-in. Pass a multipart file.

Use when you have raw bytes (clipboard screenshots, share-sheet, scripts).