# Stashr MCP server: connect your AI

> Connect ChatGPT, Claude, Codex, Cursor, and other AI tools directly to your Stashr library over the hosted Stashr MCP server.

MCP (the Model Context Protocol) is an open standard that lets AI tools connect to outside apps. Stashr has a hosted MCP server, so your assistant can search your library by meaning, read full saves, stash new links, and keep tags and collections organized from inside a conversation.

There is nothing to install and no local server to keep running. Add one URL to your AI tool, sign in to Stashr, and approve the connection. MCP access is part of [Pro](/docs/plans-and-billing) and included in every free trial.

```text
https://stashr.me/mcp
```

For clients that discover servers automatically, Stashr publishes an [MCP server card](https://stashr.me/.well-known/mcp/server-card.json) at `/.well-known/mcp/server-card.json` (transport, auth, and the full tool list) and a manifest at `/.well-known/mcp`. A plain `GET https://stashr.me/mcp` returns the same card, and the protocol handshake itself (`initialize`, `ping`, `tools/list`) works without a credential, so a client can complete discovery first; the first `tools/call` is what triggers sign-in. OAuth discovery follows the standards: `/.well-known/oauth-protected-resource/mcp` names the authorization server and scopes, and an unauthenticated request gets a `401` whose `WWW-Authenticate` header points there.

## Connect your AI tool

### ChatGPT

ChatGPT connects to Stashr as a custom MCP app in developer mode.

> **Note: ChatGPT availability**
>
> Custom MCP apps currently run on ChatGPT web. Full read and write support is available to Business, Enterprise, and Edu workspaces; Pro accounts can use custom apps for read and search actions. Workspace admins may need to enable developer mode or grant access first. Check [OpenAI's current availability](https://help.openai.com/en/articles/12584461) if the option does not appear for your account.


1. **Enable developer mode**

   In ChatGPT on the web, open **Settings → Apps → Advanced Settings** and turn on **Developer mode**. A workspace admin or owner may need to enable custom apps first.

2. **Create the app**

   From **Settings → Apps**, create a custom app named **Stashr**, use `https://stashr.me/mcp` as its MCP server URL, and scan its tools.

3. **Sign in**

   Press **Connect**, sign in to Stashr, and approve the permissions. ChatGPT stores and refreshes the OAuth connection for you.


### Claude Code

Add the hosted server from your terminal:

```sh
claude mcp add --transport http --scope user stashr https://stashr.me/mcp
```

Open Claude Code, type `/mcp`, choose Stashr, and complete the sign-in in your browser.

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.stashr]
url = "https://stashr.me/mcp"
```

Then run:

```sh
codex mcp login stashr
```

### Cursor

Create or edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` for one project):

```json
{
  "mcpServers": {
    "stashr": {
      "url": "https://stashr.me/mcp"
    }
  }
}
```

Open Cursor's MCP settings and authenticate Stashr when prompted.

> **Note: Other MCP clients**
>
> Use `https://stashr.me/mcp` as a **Streamable HTTP** server and choose OAuth when the client asks how to authenticate. For terminal automation, use the [official Stashr CLI](/docs/cli). Stashr also accepts a scoped `stashr_` API key as a Bearer token for headless clients and CI; keep it in secret storage rather than a shared config file.


## Permissions

The Stashr sign-in screen tells you exactly what the connection can do before you approve it:

- **Read your library**: search and read bookmarks, tags, and collections.
- **Update your library**: save links; edit notes, tags, and favorites; archive and restore bookmarks; and create or edit collections.
- **Delete collections**: permanently delete a collection only after an explicit confirmation. This never permanently deletes bookmarks.
- **Stay connected**: refresh the connection without making you sign in every hour.

You can deny the connection on that screen. To revoke it later, open [Settings → Authorized apps](/settings/authorized-apps) in Stashr. Revoking removes the app's consent and refresh credentials on Stashr's server. An access token already issued may continue working for up to one hour, after which the app must reconnect and ask for permission again.

## What your assistant can do

Once connected, the assistant sees thirteen Stashr tools and picks between them on its own. Search and browse return compact, bounded results; the assistant fetches full content or image previews only when the task needs them.

| Tool | What it does |
| --- | --- |
| `search` | Finds saves by meaning, with optional filters and post- or image-ranked results. Image matches include the AI caption and selected media ref. Reaches the archive with its state option. |
| `fetch` | Reads one save in full — its body rendered as Markdown, plus note, tags, author, and media details. |
| `fetch_many` | Reads up to 20 saves in full in one call, for comparing or summarizing a shortlist; reports ids that were not found. |
| `view_media` | Visually inspects up to four selected stored images as bounded previews. |
| `list_bookmarks` | Browses your library newest-first with structured filters, or a saved collection's contents by id. |
| `save_bookmark` | Saves a public URL, where it is tagged and indexed like any other save. |
| `update_bookmark` | Edits a save's note, tags, favorite state, or reversible archive state. |
| `archive_bookmarks` | Archives or restores up to 200 saves in one reversible batch. |
| `library_stats` | Aggregates counts in one call: totals plus platform, content-type, and monthly breakdowns. |
| `list_tags` | Lists your tags with usage counts so edits reuse your existing vocabulary. |
| `get_account` | Reports your plan, trial status, and remaining AI-tag quota. |
| `list_collections` | Lists saved collections (read-only). |
| `manage_collection` | Creates, updates, or—with explicit confirmation—deletes collections. |

Try asking:

- "Find that thread about pricing pages I saved a few weeks ago and summarize it."
- "Find the images I saved with warm timber reading nooks and show me the best three."
- "Save this article to Stashr and tag it competitive research."
- "Tag my saved posts from that creator with woodworking."
- "Make a collection of my saved posts about CSS tricks."

## Troubleshooting

- **The client says authentication is required**: open its MCP settings and choose **Authenticate**, or run its MCP login command again.
- **The consent page expired**: return to your MCP client and restart the connection. Authorization requests expire after ten minutes.
- **An action is forbidden**: reconnect Stashr so the client requests the current permissions. API-key connections may need a higher key access level.
- **The connection fails with a payment error**: MCP access needs Pro or an active trial; see [Plans & billing](/docs/plans-and-billing).
- **An image cannot be viewed**: `view_media` works with images archived in Stashr. Remote-only images and videos still return metadata and their original save URL.
- **A tool changed but ChatGPT still shows the old version**: custom ChatGPT apps keep a reviewed snapshot of their tools. Refresh or recreate the app in ChatGPT's app settings.

## Where to go next

- [Agent skill](/docs/agent-skill): Teach coding agents the right Stashr workflow automatically.
- [Search](/docs/search): How meaning-based search works, the same engine your AI uses.
- [API reference](/docs/api): The REST API behind every MCP tool, for direct integrations.