For agents

Agent integration

The whole contract is small: one POST to publish, one stable URL to share, one PUT to update in place. No build step, no MCP server required, no install — just HTTP.

Most agent output is HTML in spirit: a plan, a report, a prototype, a design doc. But the HTML usually lives inside a chat message — copy/paste to share, no version history, no stable address. DropFast turns those artifacts into URLs the agent can hand back to the human (or to another agent in the next turn).

The fastest path: install the prebuilt skill + CLI

Don't hand-roll HTTP tools by hand. The recommended path installs the first-party CLI and drops the hosted, REST-first DropFast skill into your agent's skill directory in one bootstrap command:

bash
npm install -g @dropfast/cli && \
  mkdir -p ~/.claude/skills/dropfast && \
  curl -fsSL https://dropfast.dev/dropfast.SKILL.md -o ~/.claude/skills/dropfast/SKILL.md

Then run dropfast login once to store your df_sk_... key. The Agent quickstart → walks through this per-harness (Claude Code, Codex, …).

No npm? The agent can write its own skill instead — paste the self-setup prompt from the quickstart: it reads the API from /llms.txt, stores your key, and writes a persistent skill so the workflow survives across sessions.

A hosted MCP server is also live at https://dropfast.dev/api/mcp (Streamable HTTP transport, Bearer auth) for clients that support remote MCP servers — Connect the MCP server → has per-client setup for Claude, Claude Code, ChatGPT, Cursor, VS Code, and Windsurf. The registry manifest lives at https://dropfast.dev/.well-known/mcp.json. In a terminal, the first-party CLI is on npm — npm install -g @dropfast/cli (see /docs/cli). The first-party MCP install packages (a stdio proxy for stdio-only clients) are still coming soon — remote-MCP clients connect today via the guide above.

Building your own tool surface (REST)

Not on the launch matrix, or want a hand-rolled integration?

  1. Add a publish tool that calls POST /api/v1/sites with the HTML the agent generated.
  2. Add an update tool that calls PUT /api/v1/sites/{slug} so the same URL evolves across turns.
  3. Surface the URL to the user in the agent's response. Persist the slug so future calls can reference it.

The endpoint surface is documented in detail in the REST API reference. Auth is an Authorization: Bearer df_sk_... header (the legacy x-api-key header is also accepted) — see Quickstart for key creation.

Minimal publish tool (TypeScript)

ts
async function dropfastPublish(input: {
  html: string;
  name: string;
  accessMode?: 'public' | 'private' | 'password' | 'restricted';
  password?: string;
  commentsEnabled?: boolean;
  // Tag at publish so the artifact is recallable later via
  // `GET /api/v1/sites?q=…&metadata.df.project=…` or the query_sites MCP
  // tool. df.project = the project/repo; df.type = plan|report|review|…
  // Untagged sites pile up as unsearchable slugs.
  metadata?: { df?: { project?: string; type?: string } };
}): Promise<{ url: string; slug: string }> {
  const form = new FormData();
  form.set('file', new Blob([input.html], { type: 'text/html' }), 'index.html');
  form.set('name', input.name);
  if (input.accessMode) form.set('accessMode', input.accessMode);
  if (input.password) form.set('password', input.password);
  // Multipart can't nest objects — send metadata as a JSON string.
  if (input.metadata) form.set('metadata', JSON.stringify(input.metadata));
  // The inline comments overlay is on by default, so a human can leave
  // structured feedback that the agent later reads via the get_comments
  // MCP tool (or `GET /api/v1/sites/<slug>/comments`). Send an explicit value
  // only when you want to opt out (pass commentsEnabled: false).
  if (input.commentsEnabled !== undefined) {
    form.set('commentsEnabled', input.commentsEnabled ? 'true' : 'false');
  }
 
  const res = await fetch('https://dropfast.dev/api/v1/sites', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.DROPFAST_API_KEY!}` },
    body: form,
  });
  const json = await res.json();
  if (!json.success) throw new Error(`${json.error.code}: ${json.error.message}`);
  return { url: json.data.url, slug: json.data.slug };
}

Patterns that work well

  • One slug per artifact, not per turn. Generate the slug on first publish, then PUT on every subsequent turn. The link the user holds always points at the latest version.
  • private for scratch, public for share. Default new artifacts to private — agents are noisy, you don't want every intermediate plan leaking. Flip to public (or password) when the user asks to share.
  • Read a private artifact back with your key, not anonymous fetch. The /s/<slug>/ origin walls a private site behind sign-in; to pull its bytes back, hit GET /api/v1/sites/{slug}/content/{path} (or dropfast fetch <slug> [path]) — it authorizes off your API key.
  • Echo the URL. Always include the URL in the agent's response text, not just as side-channel state. Humans look for the link.
  • Bulk changes go through the bulk endpoint, not a loop. Flipping access or retagging across many sites is one POST /api/v1/sites/bulk call (or dropfast bulk set|meta|rm from the CLI) — preview with dryRun: true first. There is no MCP bulk tool; use REST or the CLI.

Patterns to avoid

  • Don't publish on every keystroke. Each POST allocates a new slug. Use PUT to update.
  • Don't embed credentials in published HTML. Even in private mode, the bytes sit in S3. Treat the artifact like a public blog post.
  • Don't lose the slug. Without it, you can't update — only re-publish, which gives the user a new URL.

Deeper guides

  • Agent quickstart → — install the prebuilt skill + CLI, connect over MCP, or (fallback) have the agent write its own skill
  • Handoff → — agent-to-human handoff patterns
  • Prompts → — system prompts and tool definitions you can paste in
Edit this page on GitHub
PreviousNotificationsNext Quickstart