MCP Setup

Connect AI agents to sharedrop using the Model Context Protocol.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. sharedrop implements an MCP server that lets agents upload HTML, list pages, and share them -- all through the standard MCP tool interface.

Remote MCP (Recommended)

The simplest way to connect is using sharedrop's hosted remote MCP endpoint. No installation needed.

Configuration

Most MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf) sign in through the browser — add the server with just the URL, and approve the sign-in on first connect. No API key to create or paste:

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

Client without OAuth, or running headless (CI, a remote box)? Add a Bearer API key in a headers block instead:

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

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

Benefits

• No installation or setup
• Always up to date
• Works with any MCP client that supports remote servers
• Same rate limits as the REST API

Remote-only

The sharedrop MCP server is hosted — there is no local/stdio package to install or keep alive. If your client doesn't support remote MCP servers, use the REST API or the CLI instead.

Pair the connection 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.

upload_html (alias: paste_html)

Upload HTML content to sharedrop and get a shareable URL.

Parameters:

Name	Type	Required	Description
html	string	Yes	HTML content to upload
title	string	No	Page title (extracted from <title> if omitted)
mode	string	No	interactive (default — scripts allowed) or static (scripts stripped)
visibility	string	No	private (default), shared, or public
page_id	string	No	Existing page ID for re-upload (URL stays stable, version recorded)
workspace	string	No	Workspace ID. Ignored on workspace-scoped API keys

Returns: Page URL, page ID, slug, title, visibility, mode, and was_reupload flag.

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) — there is no 4.5 MB Vercel function-body cap on this path because the body never flows through the Vercel function. upload_file (below) remains supported as a legacy fallback for MCP clients that cannot do out-of-band binary PUTs.

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. Ignored on workspace-scoped API keys

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:

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: interactive (default) or static. Ignored for non-HTML kinds
workspace_id	string	No	Workspace ID. Ignored on workspace-scoped API keys
page_id	string	No	Existing page ID for re-upload (URL stays stable, version recorded)

Returns: Page URL, page ID, slug, mode, visibility, kind, contentType.

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.

upload_file

Upload a non-HTML document or file and get a shareable URL.

Legacy fallback retained per UPLOAD-10. upload_file accepts a base64 body inline through the MCP envelope. It is the preferred path only for MCP clients that cannot execute an out-of-band binary PUT (e.g. clients running in extremely sandboxed environments). New agent integrations should prefer create_upload + finalize_upload to avoid placing base64 in the LLM token stream.

Supported file types and MIME handling:

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	.pdf	application/pdf
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

The file extension is authoritative. The content_type parameter is treated as a hint.

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)
content_base64	string	Yes	File contents encoded as base64. data: prefixes and whitespace are stripped before decoding
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: interactive (default) or static. Ignored for non-HTML kinds (always rendered statically)
page_id	string	No	Existing page ID for re-upload
workspace	string	No	Workspace ID. Ignored on workspace-scoped API keys

Returns: Page URL, page ID, slug, title, visibility, mode, and was_reupload flag.

list_pages

List your uploaded pages.

Parameters:

Name	Type	Required	Description
limit	number	No	Results per page (default: 50)
cursor	string	No	Pagination cursor

Returns: Array of page metadata with pagination.

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.

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 calls paste_html -- Uploads the HTML 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 paste_html with the HTML]
[Agent receives https://sharedrop.cloud/agent/abc123]

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

Troubleshooting

"UNAUTHORIZED" Error

Your API key is missing or invalid. 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.