Beecargo MCP

Model Context Protocol server for the Beecargo file hosting API.

Portable marketplace packaging (Agent Plugins 1.0 + Cursor manifest) lives in ../agent-plugin.

Fastest path (agents)

Publish a durable share link with no human dashboard login:

1. Add hosted MCP with no headers: https://mcp.beecargo.net/mcp (full tools; see examples/cursor-http.mcp.json). If /mcp requires auth, use https://mcp.beecargo.net/mcp/guest for bootstrap-only tools.
2. Call beecargo_register_agent → solves a short PoW, returns bootstrap bc_* (10GB / 100rpm; session adopts the key).
3. Call beecargo_upload with a public HTTPS url → hand off https://beecargo.net/d/{shortId} (always the full share URL). Multi-file handoff: openShare: true on the first file, then shareShortId on later uploads (same link, one unlock).
4. Optional: beecargo_update_share_settings with protect: true (+ handoffMessage) on fileId or Shipment shortId → return unlockCode and handoffUrl (/h/…) on a private channel.

For production agents (100GB included concurrent storage / 1000rpm / high remote/hr): mint a Pro-tier key via dashboard POST /api-keys/agent (Pro required) or operator POST /agent/api-keys.

Skip registration for ephemeral uploads: beecargo_upload works anonymously (stricter limits; save deletionToken).

Tools

Tool	Auth	Description
beecargo_register_agent	None	Self-mint bootstrap bc_* (PoW + rate-limited)
beecargo_upload	Optional	URL, small base64, or local path (stdio); openShare / shareShortId for growable multi-file shares
beecargo_upload_status	Optional	Poll async URL upload jobs
beecargo_create_checkout	None	Mint Premium Stripe checkout (recommended: 2-day trial then weekly)
beecargo_purchase_checkout	Optional	Mint pay link for a priced share (shortId / fileId / bundleId)
beecargo_purchase_claim	None	After pay: sessionId → purchaseToken for beecargo_get_download_url
beecargo_claim_file	API key	Claim anonymous upload with claimToken
beecargo_search_tools	None	Keyword search over tools
beecargo_update_share_settings	API key	Visibility, priceCents / currency, direct, retention, protect / handoffMessage (fileId or shortId)
beecargo_connect	Dashboard key / OAuth	Seller Stripe Connect (action: status | onboard | login)
beecargo_folders	API key	Create or list folders (action: create | list)
beecargo_get_download_url	None	Signed download URL (unlockCode / unlockToken / handoffToken / purchaseToken when needed)
beecargo_file_info	Optional	Metadata by short codes (unlockRequired)
beecargo_list_files	Required	List owned files (includeFolders; optional runId for pipeline manifests)
beecargo_delete_file	Key or deletion token	Delete file

Advanced

Tool	Auth	Description
beecargo_create_upload_delegation	API key	Mint a short-lived uploadUrl + delegationToken for a worker that must not hold bc_*. Prefer beecargo_upload for normal agent uploads.

Detailed guides: upload, upload status, run artifacts, upload delegation, folders, share settings, seller payouts, and buy a priced share.

Stdio (local)

cd apps/mcp && pnpm build && pnpm start

Optional: BEECARGO_API_KEY=bc_… in env. After beecargo_register_agent, the stdio session adopts the new key automatically.

See examples/cursor-stdio.mcp.json.

HTTP (hosted)

https://mcp.beecargo.net/mcp (full tools when authenticated). Guest bootstrap: https://mcp.beecargo.net/mcp/guest. See examples/cursor-http.mcp.json.

Existing key: examples/cursor-http-with-key.mcp.json.

Env: see .env.example. Highlights:

• BEECARGO_API_URL: default https://api.beecargo.net
• BEECARGO_API_FETCH_TIMEOUT_MS: raise for large sync remotes (default guidance: 300000)
• BEECARGO_MCP_REQUIRE_AUTH: set true to require transport bearer or bc_* on /mcp (default: open bootstrap, rate-limited)
• BEECARGO_MCP_BEARER_TOKEN: optional shared transport secret when REQUIRE_AUTH=true
• BEECARGO_MERCHANT_OAUTH_ENABLED: publish OAuth resource metadata and enable Connect with Beecargo (requires matching INTERNAL_API_KEY on API + MCP)

Official MCP Registry

server.json is the Official MCP Registry manifest for io.github.Beecargo/mcp (schema 2025-12-11). The hosted remote is https://mcp.beecargo.net/mcp. Discovery copies also live at /.well-known/mcp/server.json on this host and on https://beecargo.net.

This file does not mean the server is already listed in the registry.

CLI (local scripts)

Use the dedicated package @beecargo/cli:

npx --yes github:Beecargo/cli upload ./artifact.zip --json
npx --yes github:Beecargo/cli remote https://example.com/file.bin --async --json
npx --yes github:Beecargo/cli share FILE_ID --price-cents 500 --key YOUR_BC_KEY
npx --yes github:Beecargo/cli download FILE_ID ./out.bin --purchase-token TOKEN

From the monorepo: pnpm cli upload ./artifact.zip. Publish flags (--ttl, --protect, …) match MCP beecargo_upload. share --price-cents / download --purchase-token match MCP share-settings and retrieve.

pnpm smoke:http   # MCP transport (no API)
BEECARGO_API_URL=http://localhost:3001 pnpm smoke:api   # live upload against API

Parity with lomi MCP

lomi	Beecargo
OpenAPI-generated tools	Hand-written file tools (smaller surface)
lomi_search_tools	beecargo_search_tools
Zero-header HTTP connect	Same (default); optional BEECARGO_MCP_REQUIRE_AUTH
x-lomi-api-key + OAuth	x-beecargo-api-key / Bearer bc_* + anonymous
GET/POST/DELETE /mcp	Same
/health, /ready	Same
Retries + timeout on REST	BEECARGO_API_FETCH_* env
Tool results	{ ok, status, body } + share link hints

Publish

Scope is @beecargo. First publish is manual with --otp. After that, set Trusted Publisher on the npm package to GitHub Beecargo/mcp workflow publish.yml. Then bump the patch in package.json and push main.

pnpm typecheck && pnpm publish --access public --otp=XXXXXX