# Connect your AI over MCP

> 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.

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

## Connect your AI tool

### ChatGPT

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

<Callout type="note" title="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.
</Callout>

<Steps>
  <Step title="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.
  </Step>
  <Step title="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.
  </Step>
  <Step title="Sign in">
    Press **Connect**, sign in to Stashr, and approve the permissions. ChatGPT stores and refreshes the OAuth connection for you.
  </Step>
</Steps>

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

<Callout type="note" title="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.
</Callout>

## 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 eight 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. |
| `fetch` | Reads one save in full: text, note, tags, author, and media details. |
| `view_media` | Visually inspects up to four selected stored images as bounded previews. |
| `list_bookmarks` | Browses your library newest-first with structured filters. |
| `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. |
| `list_tags` | Lists your tags so edits reuse your existing vocabulary. |
| `manage_collection` | Lists, 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.
- **Saving fails with a payment error**: saving over MCP needs an active plan or 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

<CardGroup>
  <LinkCard
    slug="search"
    title="Search"
    description="How meaning-based search works, the same engine your AI uses."
  />
  <LinkCard
    slug="collections"
    title="Collections"
    description="Saved filter sets your assistant can create and maintain."
  />
</CardGroup>