DROP DOCUMENTATION

Build with DROP

Connect AI tools to your account with Drop MCP, or automate deployments with the REST API. Both use a personal API key and publish the same static HTML, CSS and JavaScript projects.

Connect DROP to your AI workflow

DROP works with tools that can read a local site and publish it for you. Use Drop MCP with an MCP-capable client, or use the REST API from a custom Skill, script or CI job. Personal API keys are shared across both paths.

Minimum scopes for Drop MCP
projects:readprojects:writedeployments:write

Drop MCP

Drop MCP is a local MCP server that reads HTML, CSS and JavaScript files, validates the connection, and creates or atomically replaces a DROP project. The MCP client starts the process; DROP does not expose this server through a remote HTTP MCP endpoint.

Package@micropue/drop-mcp
RuntimeNode.js 20.12+
Transportstdio

Install or run the package

No global installation is required. MCP clients can start the published package with npx. Diagnostics are written to stderr; stdout is reserved for MCP protocol messages.

Terminal
$ npx -y @micropue/drop-mcp

Quick start

  1. 01
    Create an API key

    In API Keys, create a key with projects:read, projects:write and deployments:write.

  2. 02
    Configure your MCP client

    Add Drop MCP with Node.js installed and the API key available in the client's environment.

  3. 03
    Ask the client to publish

    Call drop_whoami first, then publish a local directory with drop_publish_site. Trust only the url returned by the tool.

Client configuration

All clients start the same local command. Set DROP_ALLOWED_ROOTS to a dedicated absolute sites directory so the MCP process cannot read unrelated local files.

Codex

~/.codex/config.toml

TOML
[mcp_servers.drop]
command = "npx"
args = ["-y", "@micropue/drop-mcp"]
env = { DROP_API_KEY = "YOUR_DROP_API_KEY", DROP_ALLOWED_ROOTS = "/absolute/path/to/sites" }
startup_timeout_sec = 20

Replace the placeholder key and directory with your own values.

Claude Desktop · Cursor

MCP JSON

JSON
{
  "mcpServers": {
    "drop": {
      "command": "npx",
      "args": ["-y", "@micropue/drop-mcp"],
      "env": {
        "DROP_API_KEY": "YOUR_DROP_API_KEY",
        "DROP_ALLOWED_ROOTS": "/absolute/path/to/sites"
      }
    }
  }
}

Claude Desktop uses claude_desktop_config.json. Cursor supports ~/.cursor/mcp.json or a project-level .cursor/mcp.json.

Restart required. Restart the entire MCP client after changing its configuration.

Path lists. Separate multiple allowed roots with ; on Windows and : on macOS or Linux.

Tools

ToolAccessPurposeKey parameters
drop_whoamiReadValidate the key and show account, scopes and limits.None
drop_list_projectsReadSearch and page through projects.query, page, perPage, sort
drop_get_projectReadRead project details and files.projectId or slug
drop_publish_siteWriteCreate a project or atomically replace its complete file snapshot.slug, name, path or files, ignoreUnsupported, message

For drop_publish_site, provide exactly one of path or files. For drop_get_project, provide exactly one of projectId or slug.

Environment variables

VariableRequiredDefaultPurpose
DROP_API_KEYYesNonePersonal DROP API key.
DROP_API_BASENohttps://drop.micropue.com.cn/v1API base URL.
DROP_REQUEST_TIMEOUT_MSNo20000Request timeout from 1,000 to 120,000 milliseconds.
DROP_ALLOWED_ROOTSNoMCP process working directoryFilesystem roots from which local sites may be published.
DROP_ENV_FILENoProject-root .envOptional env file location for local development.

Limits and safety

1–20files per project
512 KiBmaximum per file
1 MiBmaximum project size
50directories maximum
  • Only lowercase .html, .css and .js files are accepted.
  • Every file must be valid UTF-8 text. Hidden files and node_modules are skipped.
  • Symbolic links are rejected when publishing a directory with path.
  • Use the narrowest DROP_ALLOWED_ROOTS possible and never point it at your home directory or an entire disk.
  • Never commit a real API key or local .env file. Revoke any key that may have leaked.

Troubleshooting

ErrorMeaningResolution
missing_api_keyThe process could not read DROP_API_KEY.Set it in the client's env block or a readable .env, then restart the client.
401The key is invalid, expired or revoked.Run drop_whoami to verify the connection, or create a new key.
403The key does not have every required scope.Use a key with projects:read, projects:write and deployments:write.
409 / 412A slug or project revision changed during publishing.Read the current project again, then retry instead of repeatedly forcing the old snapshot.
413 / 422Files, paths or project parameters failed validation.Check file count, sizes, extensions, UTF-8 encoding, slug format and the path/files choice.
429 / 503Requests are rate-limited or a DROP dependency is temporarily unavailable.Honor Retry-After, keep the requestId and retry later.

REST API

The API lets scripts, CI jobs, MCP servers and Skills create projects and publish complete file snapshots. The machine-readable contract is available at /v1/openapi.json.

BASE URLhttps://drop.micropue.com.cn/v1

Authentication

Create a key in API Keys, then send it as a Bearer token. Session cookies are not accepted on /v1.

Authorization: Bearer $DROP_API_KEY
  • projects:read — list projects, read files, read deployments and usage.
  • projects:write — create projects and update metadata.
  • deployments:write — publish a new file snapshot to an existing project.
  • projects:delete — permanently delete a project.

Endpoints

MethodPathScopePurpose
GET/meAny keyAccount and key context.
GET/usageprojects:readProject and deployment usage.
GET/projectsprojects:readList projects.
POST/projectsprojects:write + deployments:writeCreate and publish.
GET/projects/{id}projects:readRead project and files.
PATCH/projects/{id}projects:writeChange metadata.
DELETE/projects/{id}projects:deleteDelete a project.
POST/projects/{id}/deploydeployments:writePublish a file snapshot.
GET/projects/{id}/deploymentsprojects:readList deployment history.

Deploy a project

A deployment replaces the complete file set. It is atomic: if validation or the transaction fails, the previous snapshot stays live. The response is returned after the new content is readable on the public content domain.

curl
curl -X POST "https://drop.micropue.com.cn/v1/projects/$PROJECT_ID/deploy" \
  -H "Authorization: Bearer $DROP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "path": "index.html", "content": "<!doctype html><h1>Version 2</h1>" }
    ],
    "message": "update hero"
  }'

Add If-Match: "rev-3" to prevent overwriting a newer revision. Add an Idempotency-Key header to make retries safe.

Limits

100projects per account
20files per project
512 KiBper file
1 MiBper project

v1 accepts only .html, .css and .js files. Read requests are limited to 300 per minute per key, writes to 60 per minute and deploys to 20 per minute.

Errors

Errors use application/problem+json with a stable code and requestId.

{
  "type": "https://drop.micropue.com.cn/developers/errors/slug-taken",
  "title": "Slug already taken",
  "status": 409,
  "code": "slug_taken",
  "detail": "Choose a different slug.",
  "requestId": "req_..."
}

DROP v1 is intentionally limited to static HTML, CSS and JavaScript.