> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stashy.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Let AI assistants work with your files over the Model Context Protocol

Stashy serves a [Model Context Protocol](https://modelcontextprotocol.io) 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](https://github.com/stashysh/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](/authentication#api-keys) as `/v1/*`, sent as a Bearer token:

```bash theme={null}
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](/api-reference/overview) — or connect through Stashy Desktop, which adds those tools.

## Stashy Desktop

[Stashy Desktop](https://github.com/stashysh/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:

```bash theme={null}
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.

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

## 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:

```json theme={null}
{
  "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](/file-access) for what `visibility` and `slug` do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.