MCP

Stashy serves a Model Context Protocol server, so AI assistants like Claude Code can list, inspect, share, and delete your files. There are two ways to connect:

	Endpoint	Tools
Server	`{HOSTNAME}/mcp`	File metadata: list, get, update, delete
Stashy Desktop	`http://127.0.0.1:7487/mcp`	Everything the server has, plus upload, replace, and download of files on your computer

Server

The server’s MCP endpoint is /mcp on the same port as the API. It uses the same API keys as /v1/*, sent as a Bearer token:

claude mcp add --transport http stashy http://localhost:8080/mcp \
  --header "Authorization: Bearer <api-key>"

Other clients that support the Streamable HTTP transport connect the same way: point them at /mcp and add the Authorization header. The server’s tools work with file metadata only. To create files or read and replace their content, use the REST API — or connect through Stashy Desktop, which adds those tools.

Stashy Desktop

Stashy Desktop is a menu bar app that keeps your API keys in the system keychain and runs a local proxy on 127.0.0.1:7487. The proxy serves MCP too, with no key needed in the client config:

claude mcp add --transport http stashy http://127.0.0.1:7487/mcp

It passes through the server’s tools with your API key added, and adds tools for files on your computer, which the server can’t reach. File contents go straight between disk and the server — they never pass through the conversation, so large files don’t use up the assistant’s context. The account is the one selected in the menu bar. To pin a specific account regardless of what’s selected, use http://<name>.localhost:7487/mcp, where <name> is the account’s name in the app.

Desktop requires Stashy server v0.10 or later. If the server has no /mcp, the local tools still work.

Tools

Server tools

Available from both endpoints.

Tool	Description
`list_files`	List your files, newest first. `limit` is 1–100 (default 50); pass the last file’s `id` as `after` to get the next page.
`get_file`	Get a file’s metadata: URL, name, content type, size, checksum, and visibility.
`update_file`	Change a file’s `slug`, `name`, or `visibility`. An empty string clears `slug` or `name`; omitted fields are left unchanged.
`delete_file`	Permanently delete a file. Its URL stops working.

Desktop tools

Available only through Stashy Desktop. Paths must be absolute.

Tool	Description
`upload_file`	Upload a local file by `path`. Optionally set `slug`, `name` (defaults to the file’s own name), `visibility`, and `content_type` (guessed from the file when omitted).
`replace_file`	Replace a file’s content with a local file, keeping its `id` and URL. Pass `checksum` from `get_file` to fail instead of overwriting changes made since.
`download_file`	Save a file to this computer. Defaults to the Downloads folder under the file’s original name. `path` can be a new file or an existing directory. Never overwrites: an explicit file path that exists fails, otherwise it picks a free name like `name (1).ext`. The content is verified against the server’s checksum.

Desktop also provides an upload prompt that takes a path and an optional visibility, uploads the file, and replies with its URL.

Results

Tools that return a file use the same shape:

{
  "id": "V1StGXR8_Z5jdHi6B-myT",
  "slug": "banner",
  "url": "https://stashy.example.com/V1StGXR8_Z5jdHi6B-myT/banner",
  "name": "banner.png",
  "content_type": "image/png",
  "size": 48213,
  "checksum": "yZRlqg==",
  "visibility": "internal",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Unlike the REST API, size is a number rather than a string. See File Access for what visibility and slug do.

Getting Started

Core Concepts

Operations

Server

Stashy Desktop

Tools

Server tools

Desktop tools

Results

​Server

​Stashy Desktop

​Tools

​Server tools

​Desktop tools

​Results

Server

Stashy Desktop

Tools

Server tools

Desktop tools

Results