stickafile-mcp

An MCP server that lets a coding agent upload a file from disk to Stickafile and hand back a shareable link. The bytes go from disk to storage and never enter the model's context.

Two tools:

• push(path, portal?, note?) → { url, name, size }

• list_portals() → the portals the token can push to

A push makes a standalone link by default. Pass a portal token when the file belongs in a project's portal instead.

Install

1. Sign in at stickafile.com, open the gear menu, choose api tokens, and create one.

2. Register the server with Claude Code, pasting the token:

   claude mcp add stickafile --scope user -e STICKAFILE_TOKEN=sf_... -- npx -y stickafile-mcp

3. In a project, ask for a link to a file:

   push dist/report.pdf and give me the link

The server checks the token once at startup. A revoked, expired, or wrong-server token makes it exit with a message in the client's MCP log instead of failing on the first push. A network failure at startup does not block it; the first call reports the problem instead.

Any MCP client works; the equivalent .mcp.json entry is:

{
  "mcpServers": {
    "stickafile": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "stickafile-mcp"],
      "env": { "STICKAFILE_TOKEN": "sf_..." }
    }
  }
}

Related MCP server: pshare-share-mcp

Configuration

Set them with more -e flags on claude mcp add, or in the env block of .mcp.json.

Agent skill

skills/stickafile/ is an agent skill that teaches an agent when to push a file, when to pass a portal, and what to do when a push fails or is refused. It is also listed on Agensi. To use it directly, copy the folder into your agent's skills directory (for Claude Code, ~/.claude/skills/stickafile/).

Links and portals

push without portal makes a link: a standalone file owned by your account, listed under Links on the dashboard, with no portal involved. This is the quick-send path and needs nothing configured beyond the token. The usual limits apply: 2 GB and 24 hours on the free plan, 10 GB and 30 days with pack credit.

push with portal puts the file in that portal instead, so it sits with a project's other files and the portal's own settings (gate, password, shared view) apply. The argument takes an 8-character portal token (e.g. a1b2c3d4), never a name. A name is guessable and an agent can invent a plausible one; a token has to come from list_portals.

STICKAFILE_PORTAL changes the default: when it is set, a push without portal goes to that portal rather than making a link. An explicit portal token still wins. If the configured portal is missing or deactivated, the push fails rather than silently falling back to a link.

note is optional plain text, up to 500 characters, shown on the download page under the file name. It is dropped on portals that have notes turned off.

Safety

push reads files, so it is the tool a prompt injection would aim at. The controls below run in the server and do not depend on the model behaving.

• STICKAFILE_ALLOW is the real boundary. path must be absolute, symlinks are resolved first, and the resolved path must sit inside one of the allowed roots. The agent cannot widen the roots.

• Deny list inside the roots. Dotfiles and dot-directories (.env, .git, .ssh, .aws, ...) and credential-shaped names are refused, with no override. The name check strips backup and double extensions (id_rsa.bak, server.key.gz) and matches credential words as whole tokens (aws_credentials, prod-secrets.yaml), so a suffix or affix does not slip a key or secret past it. As a side effect, a file whose name contains the whole word secret(s) or credential(s) is refused even when it is not sensitive (e.g. secret_plans.txt). If that is a false positive, you can rename it or copy it to a neutral name yourself, by hand, and push that. This is for the user to do; the agent is told never to rename or copy a file to get it past a refusal.

• Regular files only, and only what was vetted. vetPath opens the file once and the uploader reads from that descriptor, so the bytes uploaded are the bytes that were checked — a symlink or file swapped in after the check cannot redirect the upload. The descriptor's device and inode (on Windows, volume serial and NTFS file ID) must match the entry that passed the name checks, or the push is refused. Files with more than one hard link are refused, because a hardlinked name can point at an inode whose home is outside the workspace. If you do want to send one, make a copy yourself by hand and push the copy; the agent is told to ask you rather than make it. The API token never appears in tool output.

• Portal choice. A push to the wrong shared portal exposes the file to everyone holding that portal's link. The default is therefore a link, which only you and the people you send it to can open; the server never picks a portal on its own. Requiring a token rather than a name for portal raises the bar, but an agent that has called list_portals can still pass any token it saw, and there is no setting that forbids the argument.

Claude Code's own permission prompt is the human confirmation. The path shown there is the path that gets read.

• Don't allowlist or auto-approve push. Leave it out of permissions.allow and don't answer its prompt with "don't ask again". The checks above stop keys, secrets and files outside the workspace, but they cannot tell an ordinary project file you meant to share from one a prompt injection wants sent. Approving each upload yourself is the main defence against an injected instruction uploading a project file.

Known gap: a parent directory swapped mid-check

The open-once check pins the file: if the vetted entry is swapped for a symlink, junction, or other file before the open, the identity check refuses it. It does not pin the directories above it. A process that can write inside an allowed root could replace a parent directory with a link to somewhere else between the path being resolved and the file being opened, then put it back; the open and the identity check would then agree on the outside file. This applies on every platform. Closing it needs the operating system's path for the open handle (GetFinalPathNameByHandle, F_GETPATH, /proc/self/fd), which Node does not expose without a native module. It matters only if something other than you can write into an allowed folder and race the server, for example an agent whose shell is sandboxed without network access while this server has it.

Windows

Supported on Windows 10/11 and tested in CI on windows-latest (Node 20 and 22) alongside macOS and Linux. Separate STICKAFILE_ALLOW entries with ;, e.g. C:\Users\me\work;D:\exports; forward slashes and any drive-letter case work. Windows-specific behaviour:

• NTFS alternate data streams (notes.txt:payload, report.pdf::$DATA) are refused; only a file's main contents are uploaded.

• Reserved device names (CON, NUL, COM1, con.txt, ...) are refused, and so are \\.\ device paths and \\?\GLOBALROOT paths. \\?\C:\... long paths work.

• 8.3 short names (IDED~1, SSHDIR~1) are resolved to the long name before the name checks, so they cannot hide a denied name.

• Names ending in dots or spaces (id_rsa., server.pem ) are checked as if the trailing characters were not there.

• Junctions are treated like symlinks: resolved first, then held to the root. NTFS hard links are refused like any other multi-link file.

• Windows has no O_NOFOLLOW. A swap of the file between the check and the open is caught by the file-ID check instead.

No resume

A failed push restarts from the beginning; the abandoned server-side session is cleaned up automatically. Because a retry re-sends the whole file, push tells the agent not to retry on its own and to ask the user first.

Development

npm run test:unit                # path and deny-list tests; no network
STICKR_REPO=../stickr npm test   # plus the full e2e against a local stickr checkout

The e2e boots the Stickafile backend from a checkout of the private stickr repo, so outside contributors cannot run it; npm run test:unit is the suite that runs anywhere.

src/upload.js is a port of public/upload-core.js in the stickr repo. The retry, chunking, and presign-continuation logic must stay in step between the two; see the header comment in each.