Connector (MCP)

The connector lets an AI app use Sharedrop through its own built-in tools. It uses the Model Context Protocol (MCP), so some apps call it an MCP server.

  • Agents with a terminal (Claude Code, Codex, Gemini CLI, Cursor, VS Code, Windsurf): the CLI and skill are the better choice. Use the connector only if you can't install the CLI.
  • Chat apps (the Claude app, ChatGPT): the connector is the main way in.

Add the connector

The address is the same everywhere:

https://sharedrop.cloud/api/mcp

You sign in through the browser the first time, so there is no API key to create or paste. Each app adds it differently; pick yours for the exact steps:

Config file

Apps that read an mcpServers config file, such as Claude Code's .mcp.json, take this:

{
  "mcpServers": {
    "sharedrop": {
      "type": "http",
      "url": "https://sharedrop.cloud/api/mcp"
    }
  }
}

Other apps use different keys (VS Code uses servers, Windsurf uses serverUrl); their pages above show the right shape.

With an API key

Only for scripts, servers and apps that can't sign in through the browser. Add the key in a headers block. ChatGPT and the Claude app don't accept keys.

{
  "mcpServers": {
    "sharedrop": {
      "type": "http",
      "url": "https://sharedrop.cloud/api/mcp",
      "headers": {
        "Authorization": "Bearer sd_your_api_key_here"
      }
    }
  }
}

Replace sd_your_api_key_here with your key. See Authentication for how to create one.

Remote-only

The Sharedrop connector is hosted, so there is no local package to install or keep running. If your app can't add a remote server, use the CLI or the REST API instead.

Pair the connector with the agent skill so your agent also knows when to reach for Sharedrop and which defaults to use.

Available Tools

The MCP server exposes the following tools. Every file, including HTML, uses the same streamed upload pipeline. Supply page_id when replacing an existing page.

Uploading a large or opaque file (a database dump, a build tarball, anything over 30 MB)? On Pro and Team accounts the server also exposes create_archive_upload, sign_archive_parts, complete_archive, and abort_archive for streaming download-only archives up to 10 GB. See the Archives guide for the agent flow.

list_workspaces

List the team workspaces you belong to: id, name, slug (the workspace address), role, tier, can_upload and can_edit_all_pages. No parameters. An owner can upload and edit, re-upload or delete every page (can_upload: true, can_edit_all_pages: true); a member can too, on every page in the workspace (true, true); a viewer is read only (false, false). Check can_upload before uploading to a workspace. Pass a workspace's address or id as workspace to create_upload, finalize_upload, list_pages, list_folders, create_folder, create_reservation and list_reservations. An empty list means uploads go to your personal space. A workspace-scoped key sees only its own workspace. whoami returns the same list as workspaces.

In the dashboard, Settings > Info shows your MCP endpoint and each workspace's address, id and workspace value, with a copy button on each. Copy for your agent copies them all as plain text, without any key.

create_upload

Phase 15 direct-streamed upload, step 1 of 2. Reserves an object_key, runs the tier + storage gate, and mints a 5-minute HS256 upload token. The agent then streams the body out-of-band with curl -T, and calls finalize_upload to sanitise and publish.

Use create_upload + finalize_upload for files of any kind (HTML, image, PDF, Markdown, MHTML, JSON, JSONL), so there is no 4.5 MB Vercel function-body cap on this path because the body never flows through the Vercel function. This is the only upload path: raw bytes are never base64-encoded into the MCP envelope.

Size limits: each file can be up to the plan's per-file limit (Free 10 MB, Pro and Team 100 MB). HTML and other text files (Markdown, code, plain text, JSON, JSONL, MHTML, skills, Word documents, spreadsheets) and SVG images are capped at 10 MB on every plan. Larger content can be uploaded as a zip with create_archive_upload and is stored as a download-only archive (Pro and Team). A bundle finished with finalize_bundle is capped at the plan's per-file limit across all its files together. create_upload refuses an oversized file with FILE_SIZE_EXCEEDED before any bytes are sent; the error carries limitBytes and requestedBytes. whoami reports these limits up front: entitlements.maxFileSizeBytes (the plan limit), entitlements.maxTextFileSizeBytes (HTML, other text files and SVG) and entitlements.maxArchiveBytes (archives, 0 when the plan cannot upload them).

For a file you will finish with finalize_bundle, sign the root with an HTML filename (e.g. index.html) and each asset with a filename that has the same extension as its bundle path; otherwise finalize_bundle refuses it with 400 file_name_mismatch.

Parameters:

NameTypeRequiredDescription
filenamestringYesFilename including extension (e.g. report.pdf)
content_typestringYesMIME type (e.g. application/pdf)
size_bytesnumberYesExact body size in bytes. Must match the Content-Length of the subsequent PUT
workspacestringNoWorkspace id or address (from list_workspaces). A workspace-scoped key can only use its own workspace
reservation_idstringNoClaim a reserved address (from create_reservation). The finished upload becomes a NEW page at the reserved URL. Mutually exclusive with page_id. See Reserved addresses

Workspaces are part of the Team plan and are created in the dashboard, not through MCP. Anyone invited to one can upload to it with workspace, whatever their own plan. Call list_workspaces to find the address. A workspace you are not a member of fails with Workspace not found or you are not a member. See Workspaces and seats.

Returns: upload_url (the https://uploads.sharedrop.cloud/<object_key> endpoint the agent PUTs to), upload_token (the 5-min HS256 JWT to put in the Authorization: Bearer ... header), finalize_url, object_key.

Recommended out-of-band PUT:

curl -X PUT "$UPLOAD_URL" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -H "Content-Type: application/pdf" \
  -H "Content-Length: $(stat -f%z report.pdf)" \
  --data-binary @report.pdf

The upload token expires 5 minutes after issuance. If the PUT fails after expiry, call create_upload again to mint a fresh token (the previous object_key is abandoned and gets garbage-collected by the bucket's 24-hour lifecycle rule).

finalize_upload

Phase 15 direct-streamed upload, step 2 of 2. Validates the upload token, re-reads the quarantine object, runs the kind-dispatched sanitiser (DOMPurify for HTML, sharp for images, pdf-lib for PDFs), promotes the sanitised bytes to the public bucket, and creates the page row.

Parameters:

NameTypeRequiredDescription
object_keystringYesThe object_key returned by create_upload
upload_tokenstringYesThe upload_token returned by create_upload
titlestringNoPage title. Defaults to the document title (HTML/PDF) or filename stem
visibilitystringNoprivate (default), shared, or public
modestringNoHTML only: static or interactive. Default: a new page takes your account's default upload mode (initially interactive; configure in Settings) and a re-upload with page_id keeps the page's current mode. Ignored for non-HTML kinds
workspacestringNoWorkspace id or address (from list_workspaces). A workspace-scoped key can only use its own workspace
page_idstringNoExisting page ID for re-upload (URL stays stable, version recorded)
folder_idstringNoTarget folder ID for placement, in the same space as the upload. New uploads only (personal folders need Pro and above; workspace folders come with Team); ignored on re-upload
folder_pathstringNoTarget folder by path (e.g. reports/2026), auto-creating any missing segments. With workspace, the path is in that workspace's folders. New uploads only. folder_id wins if both are set
slidesbooleanNoHTML only: publish as a slide deck with fullscreen Present mode. Equivalent to a <meta name="sharedrop:kind" content="slides"> marker in the file. Ignored for non-HTML kinds

Returns: Page URL, page ID, slug, the effective mode, visibility, kind, was_reupload, version (1 for a new page, up by one on every re-upload), scripts_will_run, external_resource_hosts, and a warnings array that is always present (possibly empty). Each warning contains code, detail, count and message; the codes are removed_tag, removed_attribute, images_extracted (inline images moved to hosted storage) and external_refs_block_scripts (external hosts that stop an interactive page's scripts while external network is off). A new page also returns same_title_pages: up to 5 of your pages with exactly the same title, newest first, as a hint to pass page_id if you meant to revise one. sanitiser_warnings (removals only, omitted when empty) is kept for older clients. See finalize for every field.

Busy page: if another upload of the same page is still finishing, the tool returns at once with an error carrying status: 409, retryable: true, a reason (page_mutation_in_progress or target_page_pending) and retry_after_seconds. Wait that many seconds and call the same tool again with the same arguments; do not upload the bytes again. finalize_bundle behaves the same way.

Example agent flow (PDF, no base64 in the LLM token stream):

1. AGENT: create_upload({ filename: "report.pdf", content_type: "application/pdf", size_bytes: 482190 })
   → { upload_url, upload_token, finalize_url, object_key }

2. AGENT shell: curl -T report.pdf -H "Authorization: Bearer $TOKEN" "$UPLOAD_URL"
   → 201 { ok: true, object_key, bytes: 482190 }

3. AGENT: finalize_upload({ object_key, upload_token, visibility: "public" })
   → { url: "https://sharedrop.cloud/agent/x8vh3p", page_id, ... }

4. AGENT to user: Here is your report: https://sharedrop.cloud/agent/x8vh3p

Notice that no base64 of the PDF was ever placed in the LLM context; the body flows out-of-band, only the URL + small JSON envelopes flow through the model.

Supported file types

create_upload + finalize_upload accept every supported kind, HTML included. The file extension is authoritative; the content_type parameter is treated as a hint.

KindExtensionsMIME type(s)
HTML.html, .htmtext/html
MHTML web archives.mhtml, .mhtmultipart/related, application/x-mimearchive
Markdown.md, .markdowntext/markdown
PDF.pdfapplication/pdf
JSON.jsonapplication/json
JSONL.jsonlapplication/jsonl
Image (broad support).png, .jpg, .jpeg, .webp, .gif, .avif, .bmp, .ico, .apng, .svgimage/png, image/jpeg, image/webp, image/gif, image/avif, image/bmp, image/x-icon, image/apng, image/svg+xml
Image (limited browser support).heic, .heif, .tif, .tiffimage/heic, image/heif, image/tiff
Video.mp4, .webm, .mov, .m4vvideo/mp4, video/webm, video/quicktime

HTML has one variant: pass slides: true (or include the in-file marker) and the page publishes as a slide deck with fullscreen Present mode instead of an ordinary page.

Slide decks and Present mode

When you generate a presentation rather than a document, publish it as a deck so the user can put it straight on a TV or a projector. Structure the HTML as top-level <section> elements, one per slide, then either add <meta name="sharedrop:kind" content="slides"> to the file or pass slides: true to finalize_upload. The response comes back with "kind": "slides".

The user presents it by clicking Present in the dashboard, or by opening the page URL with ?present=1. On Pro you can also hand them a link that lands straight in Present mode:

// create_ephemeral_link
{ "page_id": "...", "expires_in_seconds": 14400, "present_only": true }

Give the user the returned url verbatim, since that is the copy carrying &present=1. present_only works on decks only and requires Pro. Full details, including the keyboard controls and kiosk autoplay, are in the slide decks guide.

Upload and re-upload

There are two business operations, and both run the identical create_upload then PUT then finalize_upload sequence:

  • Upload creates a new page. Omit page_id.
  • Re-upload replaces an existing page. Pass the same page_id to create_upload (it is bound into the signed token) and to finalize_upload. The URL, slug, version history, shares, and folder placement are all preserved, and a new version is recorded. A workspace page needs no workspace: Sharedrop finds it from page_id.

list_pages

List your uploaded pages.

Parameters:

NameTypeRequiredDescription
limitnumberNoResults per page (default: 50)
cursorstringNoPagination cursor
workspacestringNoList a workspace's pages, by id or address (from list_workspaces)

Returns: Array of page metadata with pagination.

update_page

Update a page's metadata. Pass slug to rename a public page to a custom address. It requires Pro or higher, allows up to 10 renames per page, and follows the custom-address rules: 3 to 60 lowercase letters, numbers, and hyphens; no leading or trailing hyphen, consecutive hyphens, reserved words, or generated-looking addresses. Previous addresses permanently send a 301 redirect to the current address and cannot be reused. If the page becomes private or shared, it returns to a generated random address and the custom address stops resolving.

Parameters:

NameTypeRequiredDescription
page_idstringYesID of the page to update
slugstringNoCustom address for a public page (Pro plan or higher)

fetch_page

Pull a page's raw content into the agent's context: its own page, a public one, or one shared to it. Returns a short-lived signed fetch_url plus metadata; the agent then HTTP GETs fetch_url (no auth header; the token is in the URL) to read the raw bytes. This is the content path; get_page stays metadata-only. Not a zip, not the sandboxed viewer wrapper. Available on every tier (entitlements.fetch in whoami).

Parameters:

NameTypeRequiredDescription
page_idstringYesPage ID to fetch
versionnumber or "latest"NoFetch the exact file uploaded for this version instead (from list_versions)

Returns: fetch_url, expires_at, content_type, mode, and size. GET fetch_url within ~5 minutes to stream the raw bytes.

With version, fetch_page returns fetch_url, expires_at, version, filename and content_type instead, and fetch_url serves that version's original upload as a download (a folder upload as a zip; HTML and SVG come as application/octet-stream). This needs version access on the page, as list_versions does. The URL works for that one version for about 5 minutes, for anyone holding it, and revoking the API key does not cancel a link already handed out. Without version, fetch_page works as above.

Archive pages have no fetch_url. For an archive, fetch_page returns an error with code ARCHIVE_DOWNLOAD_REQUIRED and a download_url: GET it with your Sharedrop Bearer credential and it redirects to the file. An unknown page returns PAGE_NOT_FOUND.

An image or video page that is still in its safety check can only be fetched by its owner. An image, video or archive page whose paying plan lapsed more than 14 days ago cannot be fetched by anyone until the plan is restored. Both return PAGE_NOT_FOUND.

list_versions

List a page's versions: the current one (live: true, selector: "latest") and every earlier version kept, newest first. Each has its version number, file_size, kind, content_type, created_at and has_original (whether the exact uploaded file was kept). To read one, call fetch_page with its version number.

Parameters:

NameTypeRequiredDescription
page_idstringYesPage ID

Returns: { "versions": [...] }, the same list as GET /api/v1/pages/:id/versions.

You need version access on the page: your own page, or any page in a workspace you belong to, whatever your role. Anything else returns PAGE_NOT_FOUND.

Pro and Team accounts can hand out a separate link that stops working after a time limit or a number of views. It never changes the page's own visibility or share list.

ToolWhat it does
create_ephemeral_linkCreate a link: page_id, audience ("anyone" or "people"), emails (for "people"), notify, expires_in_seconds, max_views, present_only
list_ephemeral_linksA page's links with status, views, limits and people
update_ephemeral_linkAdd or remove people: page_id, link_id, add_emails, remove_emails, notify
revoke_ephemeral_linkStop a link now
// create_ephemeral_link: only these people, after they sign in
{ "page_id": "...", "audience": "people", "emails": ["board@example.com"], "max_views": 5 }

Give the user the returned url verbatim. On a "people" link Sharedrop emails each person the link and its limits (and anyone added later with update_ephemeral_link); pass notify: false if the user wants to send it themselves. These emails count toward the daily share-email limit (10 on Free, 500 on Pro, 2000 on Team); when it cannot cover everyone the link is still created and the result carries email_warning saying how many people were not emailed, with a message to pass on to the user. Full details are in the Disappearing links guide.

share_page

Share a page with someone by email.

Parameters:

NameTypeRequiredDescription
page_idstringYesPage ID to share
emailstringYesEmail address to share with

Returns: Access grant details. share_with_email does the same for one email or a list, and returns one result per email.

Each recipient gets an invitation email, up to a daily limit per account: 10 on Free, 500 on Pro, 2000 on Team. Over the limit the share still succeeds but no email is sent. Each share that was not emailed carries its own email_warning (a share with null is emailed), and the top-level email_warning says how many of the recipients were not emailed. Tell the user, and give them the page URL to send to those people themselves. See Daily email limit.

list_shared_with_me

List the pages other people have shared with you, newest share first. Read-only. Each share has page_id, title, kind, url (the page's path), full_url (the full link), shared_by (the sharer's handle), shared_at and expires_at (null when the share does not end). Read one with fetch_page and its page_id.

Parameters:

NameTypeRequiredDescription
limitnumberNoShares per call (default: 50, max 100)
cursorstringNonext_cursor from the previous call

Returns: { "shares": [...], "next_cursor", "has_more" }, the same rows as GET /api/v1/shared.

Shares belong to a person, so a workspace-scoped key gets FORBIDDEN (Shares belong to a person, not a workspace. Use a personal API key.). Connect with a personal key or by signing in.

Folders

Personal folders need a Pro plan or higher. A Team workspace has its own folder tree, which comes with the Team plan whatever a member's personal plan. Owners and members manage workspace folders; viewers can only list them.

ToolWhat it does
list_foldersList folders. Omit parent_id for the top level, or pass it for a folder's direct children. Pass workspace (id or address) for a workspace's folders
create_folderCreate a folder from name, with an optional parent_id in the same space. Pass workspace to create it in a workspace
move_pageMove a page into a folder (parent_id) or to the top level (null). Works on workspace pages; the folder must be in the page's own space
delete_folderDelete a folder, personal or workspace. A non-empty one needs force: true, which moves it and its contents to the trash
restore_pageRestore a trashed page or folder

move_page and delete_folder take no workspace: Sharedrop uses the page's or folder's own space. A workspace (sdw_) key always works in its own workspace. Owners and members can move or delete any workspace folder, whoever created the pages in it. A folder in the other space returns A folder and its pages must be in the same space.

Reserved addresses

Reserve a stable sharedrop.cloud address before any content exists, so you can hand out the final URL up front and fill it in later. See the Reserved addresses guide for the full flow and the placeholder/expiry behavior.

create_reservation

Reserve an address and get back the final URL plus a one-time claim token. The claim_token (an sdr_ credential) is shown exactly once and can never be retrieved again, so store it now and hand it to the agent over a secure channel.

Parameters: all optional.

NameTypeRequiredDescription
titlestringNoPage title shown once the address is claimed (default Untitled)
descriptionstringNoOptional description for your own reference
intended_agent_namestringNoName of the agent this address is held for (shown in the dashboard)
visibilitystringNoprivate (default), shared, or public. The claimed page inherits it
slugstringNoOptional custom address for a public reservation (Pro plan or higher)
modestringNoHTML render mode the claimed page takes: static or interactive
expires_atstringNoISO 8601 datetime after which an unclaimed reservation expires. Omit to keep it until claimed or revoked
folder_idstringNoPro folder to file the claimed page into
workspacestringNoReserve the address in a workspace, by id or address (from list_workspaces)

Returns: the serialized reservation with url (the relative path) and full_url (the absolute link), plus the one-time claim_token. For an HTML claim, the path stays the same. For shared HTML, the host can change to the workspace custom domain. Use the url or full_url returned by the finalize call. Over your plan's cap (Free 2, Pro 25, Team unlimited) the call returns a billing error you can relay to the user.

For slug, use 3 to 60 lowercase letters, numbers, and hyphens. It cannot start or end with a hyphen, contain consecutive hyphens, be a reserved word, or look like a generated address.

Claim the address: call create_upload with reservation_id set to the reservation's id (instead of page_id), then PUT the bytes and call finalize_upload. The first upload becomes a live page at the reserved path, inheriting the visibility, mode, and folder chosen at reserve time. Subsequent updates use page_id as normal.

list_reservations

List your reserved addresses. Each entry shows its status (reserved, claimed, expired, or revoked), the final URL, and the metadata chosen at reserve time. Claim tokens are one-time and shown only by create_reservation, so they never appear here.

Parameters:

NameTypeRequiredDescription
limitnumberNoResults per page (default: 50)
cursorstringNoPagination cursor
workspacestringNoList a workspace's reservations, by id or address

revoke_reservation

Revoke a reservation. The row is kept (status flips to revoked) and the sdr_ claim token is permanently invalidated.

Parameters:

NameTypeRequiredDescription
reservation_idstringYesID of the reservation to revoke (from create_reservation or list_reservations)

Example Workflow

Here is what a typical AI agent interaction looks like with sharedrop MCP:

  1. Agent generates HTML: Creates a report, dashboard, or visualization
  2. Agent streams the upload: Calls create_upload, PUTs the raw HTML to the signed URL, then calls finalize_upload with a title
  3. Agent receives URL: Gets back a shareable sharedrop.cloud link
  4. Agent shares the link: Sends the URL to the user in chat, or calls share_page to grant email access
User: "Generate a sales dashboard for Q1 2026"

Agent: I'll create that dashboard and share it with you.

[Agent generates HTML dashboard]
[Agent calls create_upload, PUTs the HTML, then finalize_upload]
[Agent receives https://sharedrop.cloud/agent/abc123]

Agent: Here's your Q1 2026 sales dashboard:
https://sharedrop.cloud/agent/abc123

Custom domains

If the account behind the API key has a live custom domain, the url returned by finalize_upload, get_page, list_pages and update_page is the branded address on that domain, for example https://share.yourcompany.com/yourhandle/abc123. Surface it to the user exactly as returned; do not reassemble a URL from a hostname of your own. A page in a Team workspace uses the workspace's custom domain, which the workspace owner manages.

The MCP server itself stays on sharedrop.cloud, and so does your API key. Only the recipient URL is branded. A page that is not eligible, a private page or an archive, keeps its sharedrop.cloud address.

Custom domains cover public pages on subdomains only, using exactly two records: one CNAME for the share subdomain and one CNAME for the view subdomain. See Custom domains.

Errors worth understanding

The server instructions hand your agent the same short list:

  • TIER_LIMIT (a new page would pass the plan's page limit, or the file kind is not on the plan: delete a page or upgrade)
  • FILE_SIZE_EXCEEDED (split or compress; HTML and other text files are capped at 10 MB on every plan, so upgrading does not raise that limit; upload larger content as a zip archive on Pro or Team)
  • VALIDATION_ERROR (unsupported file type or bad input)
  • PAYMENT_REQUIRED (the account is read only after a failed payment; the owner must update their card. Reads still work, except that images, video and archives are refused from 14 days after the lock)

"PAYMENT_REQUIRED" Error

A subscription payment failed and was still unpaid 21 days later, so the account is read only. The tool returns the server's message unchanged:

Error [PAYMENT_REQUIRED]: Your account is read only because a payment failed. Update your card at sharedrop.cloud/dashboard/settings/billing to start uploading again.

Relay that message to the person you are working for and stop trying to write. There is no upsell and nothing to retry: only a successful payment lifts the lock, and it lifts on its own when one lands.

The tools that start a write are refused: create_upload, create_archive_upload, update_page, move_page, restore_page, share_with_email and create_ephemeral_link. Read tools keep working, so whoami, list_pages, get_page, fetch_page and list_shares are all still available, and so is delete_page. The lock drops the plan to Free, so from 14 days after it fetch_page returns PAGE_NOT_FOUND for images, video and archives until the plan is restored. See Failed payments.

For a Team workspace the message names the workspace instead, and a member is asked to get a workspace owner to update the card.

Troubleshooting

"UNAUTHORIZED" Error

Your sign-in or API key is missing or invalid. If you signed in through the browser, sign in again from your app's connector settings. If you use a key, verify:

  • The key starts with sd_ or sdw_
  • The key hasn't been revoked
  • The Authorization header format is Bearer <key>

"RATE_LIMIT_EXCEEDED" Error

You've hit the rate limit for your plan tier. Wait for the rate limit window to reset (60 seconds) or upgrade your plan for higher limits.

Connection Timeout

Ensure your network can reach https://sharedrop.cloud.