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/mcpYou 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:
- Claude Code
- Codex
- Gemini CLI
- Cursor
- VS Code
- Windsurf
- Claude app (desktop, web and phone)
- ChatGPT
- Any other app
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, andabort_archivefor 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:
| Name | Type | Required | Description |
|---|---|---|---|
filename | string | Yes | Filename including extension (e.g. report.pdf) |
content_type | string | Yes | MIME type (e.g. application/pdf) |
size_bytes | number | Yes | Exact body size in bytes. Must match the Content-Length of the subsequent PUT |
workspace | string | No | Workspace id or address (from list_workspaces). A workspace-scoped key can only use its own workspace |
reservation_id | string | No | Claim 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.pdfThe 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:
| Name | Type | Required | Description |
|---|---|---|---|
object_key | string | Yes | The object_key returned by create_upload |
upload_token | string | Yes | The upload_token returned by create_upload |
title | string | No | Page title. Defaults to the document title (HTML/PDF) or filename stem |
visibility | string | No | private (default), shared, or public |
mode | string | No | HTML 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 |
workspace | string | No | Workspace id or address (from list_workspaces). A workspace-scoped key can only use its own workspace |
page_id | string | No | Existing page ID for re-upload (URL stays stable, version recorded) |
folder_id | string | No | Target 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_path | string | No | Target 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 |
slides | boolean | No | HTML 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/x8vh3pNotice 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.
| Kind | Extensions | MIME type(s) |
|---|---|---|
| HTML | .html, .htm | text/html |
| MHTML web archives | .mhtml, .mht | multipart/related, application/x-mimearchive |
| Markdown | .md, .markdown | text/markdown |
.pdf | application/pdf | |
| JSON | .json | application/json |
| JSONL | .jsonl | application/jsonl |
| Image (broad support) | .png, .jpg, .jpeg, .webp, .gif, .avif, .bmp, .ico, .apng, .svg | image/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, .tiff | image/heic, image/heif, image/tiff |
| Video | .mp4, .webm, .mov, .m4v | video/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_idtocreate_upload(it is bound into the signed token) and tofinalize_upload. The URL, slug, version history, shares, and folder placement are all preserved, and a new version is recorded. A workspace page needs noworkspace: Sharedrop finds it frompage_id.
list_pages
List your uploaded pages.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
limit | number | No | Results per page (default: 50) |
cursor | string | No | Pagination cursor |
workspace | string | No | List 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:
| Name | Type | Required | Description |
|---|---|---|---|
page_id | string | Yes | ID of the page to update |
slug | string | No | Custom 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:
| Name | Type | Required | Description |
|---|---|---|---|
page_id | string | Yes | Page ID to fetch |
version | number or "latest" | No | Fetch 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:
| Name | Type | Required | Description |
|---|---|---|---|
page_id | string | Yes | Page 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.
Disappearing links
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.
| Tool | What it does |
|---|---|
create_ephemeral_link | Create a link: page_id, audience ("anyone" or "people"), emails (for "people"), notify, expires_in_seconds, max_views, present_only |
list_ephemeral_links | A page's links with status, views, limits and people |
update_ephemeral_link | Add or remove people: page_id, link_id, add_emails, remove_emails, notify |
revoke_ephemeral_link | Stop 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:
| Name | Type | Required | Description |
|---|---|---|---|
page_id | string | Yes | Page ID to share |
email | string | Yes | Email 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:
| Name | Type | Required | Description |
|---|---|---|---|
limit | number | No | Shares per call (default: 50, max 100) |
cursor | string | No | next_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.
| Tool | What it does |
|---|---|
list_folders | List 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_folder | Create a folder from name, with an optional parent_id in the same space. Pass workspace to create it in a workspace |
move_page | Move 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_folder | Delete a folder, personal or workspace. A non-empty one needs force: true, which moves it and its contents to the trash |
restore_page | Restore 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.
| Name | Type | Required | Description |
|---|---|---|---|
title | string | No | Page title shown once the address is claimed (default Untitled) |
description | string | No | Optional description for your own reference |
intended_agent_name | string | No | Name of the agent this address is held for (shown in the dashboard) |
visibility | string | No | private (default), shared, or public. The claimed page inherits it |
slug | string | No | Optional custom address for a public reservation (Pro plan or higher) |
mode | string | No | HTML render mode the claimed page takes: static or interactive |
expires_at | string | No | ISO 8601 datetime after which an unclaimed reservation expires. Omit to keep it until claimed or revoked |
folder_id | string | No | Pro folder to file the claimed page into |
workspace | string | No | Reserve 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:
| Name | Type | Required | Description |
|---|---|---|---|
limit | number | No | Results per page (default: 50) |
cursor | string | No | Pagination cursor |
workspace | string | No | List 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:
| Name | Type | Required | Description |
|---|---|---|---|
reservation_id | string | Yes | ID 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:
- Agent generates HTML: Creates a report, dashboard, or visualization
- Agent streams the upload: Calls
create_upload, PUTs the raw HTML to the signed URL, then callsfinalize_uploadwith a title - Agent receives URL: Gets back a shareable
sharedrop.cloudlink - Agent shares the link: Sends the URL to the user in chat, or calls
share_pageto 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/abc123Custom 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_orsdw_ - The key hasn't been revoked
- The
Authorizationheader format isBearer <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.