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

Advanced

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

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