# Connect AI Assistants to X02 with MCP

> Connect Claude, Cursor, or any Model Context Protocol client to your X02 account. Upload, search, organize, and share files by asking — with scoped, revocable access and no API key pasted into the client.

Source: https://x02.me/blog/connect-ai-assistants-to-x02-with-mcp · 2026-09-21 · X02 Team

You can now let an AI assistant work on your X02 files for you — find an old upload, look at an image, add a new file, tidy things into folders, hand you a share link. You ask; it does the clicking.

It works because X02 speaks **[the Model Context Protocol](https://modelcontextprotocol.io)** (MCP), the open standard AI apps use to connect to outside services. In practice that means you paste one address into Claude, ChatGPT or Cursor, sign in to X02 once in your browser, and you are done. You never copy an API key into the AI app.

**Just want it working?** [Set Up X02 in Claude, ChatGPT, Cursor and More](/blog/set-up-x02-mcp-in-your-ai-client) is the step-by-step for each app. This page is the *why* — what an assistant can reach, what it cannot, and what happens to your credentials.

> [!TIP]
> **Quick Navigation:**
> * [What This Actually Gets You](#what-this-actually-gets-you)
> * [Connecting a Client](#connecting-a-client)
> * [What the Assistant Can Do](#what-the-assistant-can-do)
> * [Permissions and Scopes](#permissions-and-scopes)
> * [How Sign-In Works](#how-sign-in-works)
> * [Disconnecting an App](#disconnecting-an-app)
> * [Limits and Gotchas](#limits-and-gotchas)
> * [Next Steps & Related Tutorials](#next-steps--related-tutorials)

---

## What This Actually Gets You

The REST API already lets you script X02. MCP is for the other case: when an AI assistant is doing the work and you want it to reach your account **safely**.

The difference that matters is the credential. An API key is all-or-nothing — handing one to a third-party app gives it everything your account can do, forever, and taking it back means rotating the key and breaking every other integration you own. MCP uses OAuth instead:

| | API Key | MCP (OAuth) |
|---|---|---|
| **What the app holds** | Your full account key | Its own token, scoped to what you approved |
| **Where you type it** | Into the app | Nowhere — you sign in on x02.me |
| **Limiting what it can do** | Not possible | Per-scope, shown before you approve |
| **Revoking one app** | Rotate the key, break everything else | Disconnect that app only |

Use the API key for your own code. Use MCP for software you did not write.

---

## Connecting a Client

The server lives at **`https://up.x02.me/mcp`**.

### Claude Code

```bash
claude mcp add --transport http x02 https://up.x02.me/mcp
```

### Claude Desktop, Cursor, Windsurf, and others

Add a remote MCP server in the client's settings and give it the same URL:

```
https://up.x02.me/mcp
```

### Trying it by hand

The official MCP Inspector is useful for browsing the tools and calling them manually:

```bash
npx @modelcontextprotocol/inspector
```

Whichever client you use, it will open a browser window the first time you connect. Sign in to X02, review what the app is asking for, and approve. The client stores its own token from there.

![Architecture Diagram](/blog-diagrams/connect-ai-assistants-to-x02-with-mcp-1.svg)

---

## What the Assistant Can Do

Fifteen tools, covering the things you would otherwise do in the dashboard:

| Tool | What it does |
|---|---|
| `get_account` | Your plan, storage use, and how much of today's upload quota is left |
| `list_files` | Page through uploads, narrowing by search, folder, file kind and upload date |
| `get_file` | URL, size, type, folder, views, and expiry for one file |
| `view_file` | Shows the assistant a downscaled thumbnail of an image, so it can identify a file instead of guessing. Images only |
| `request_file_from_user` | Gives you a link to drop a file into — how an attachment reaches X02 |
| `check_file_handoff` | Collects what you dropped, waiting for the upload so you never have to say "done" |
| `upload_file` | Upload small file content directly (see the size note below) |
| `upload_from_url` | Rehost an image that is already online, by URL. Images only |
| `rename_files` | Rename one or more stored files |
| `move_files` | Move one or many files into a folder, or back to the root library |
| `delete_files` | Permanently delete one or more files |
| `list_folders` | Folders with file counts and share status |
| `create_folder` | Create a folder |
| `delete_folder` | Delete a folder. Files inside return to the root library rather than being deleted |
| `share_folder` | Publish a folder as a shared album and return the link, or stop sharing it |

In practice you do not call these by name. You ask:

> "Upload this screenshot and give me the link."
> "Find the invoice PDF I uploaded last month."
> "Make a folder called Release v3 and move everything from this week into it."
> "Share the Screenshots folder and send me the album link."

---

## Permissions and Scopes

Every connection is scoped. The consent screen lists exactly what the app asked for before you approve it:

| Scope | Grants |
|---|---|
| `account:read` | Read your username, plan, limits, and usage |
| `files:read` | List and inspect your files |
| `files:write` | Upload, rename, and move files |
| `files:delete` | Delete files |
| `folders:read` | List your folders |
| `folders:write` | Create, delete, and share folders |

These are enforced on every single call, not just at sign-in. An app that was granted `files:read` and later tries to delete something gets refused — the request never reaches your files.

> [!NOTE]
> **Deleting is permanent.** `delete_files` and `delete_folder` are marked destructive so clients can prompt you first, but X02 has no trash can.
>
> Note that the two are gated separately. `files:delete` covers `delete_files`; deleting a *folder* is part of `folders:write`, alongside creating and sharing them. Withholding `files:delete` stops an app removing your files, but it can still delete a folder if it holds `folders:write` — the files inside return to your root library rather than being destroyed, so nothing is lost, but the folder is gone.

---

## How Sign-In Works

Worth understanding, because it is the part that protects you.

1. The client discovers the server's capabilities from a metadata document — no configuration beyond the URL.
2. It registers itself and sends your browser to X02 with a cryptographic challenge (PKCE).
3. You sign in on **x02.me**, not in the app, and see what is being requested.
4. On approval, X02 issues an access token bound to that one app and those scopes. It lasts an hour, alongside a refresh token the client rotates to stay connected for up to thirty days without asking you again.

Two details that matter:

**The consent screen shows where you will be sent back to.** Any developer can register a client and name it anything — "X02 Official" included. The name is self-declared; the redirect destination is not. If that host is not the app you just clicked in, deny it.

**Your API key never leaves X02.** The server resolves your account from the app's token internally. The app cannot read your key, and a leaked token cannot be turned into one.

---

## Disconnecting an App

Revoking is per app, and this is the part worth reading properly.

Remove the connector in your client and it discards the tokens it holds. Well-behaved clients also call X02's revocation endpoint on the way out, which kills those tokens on our side at the same moment. Not every client does, and there is no way for us to tell from the outside which one you are using.

So, to be precise about what you are guaranteed:

- **Your API key, your folder keys and every other connected app are unaffected.** That part is absolute — this is the whole reason to prefer MCP over handing out a key.
- **If the client revokes on disconnect, access ends immediately.**
- **If it does not,** the access token it already holds keeps working until it expires — at most an hour — and its refresh token would remain valid for thirty days.

> [!NOTE]
> X02 does not yet have a page listing your connected apps, so revocation is currently driven by the client rather than by you. If you need a connection dead *now* and are not certain your client revoked it, email [contact@x02.me](mailto:contact@x02.me) or ask in [our Discord](https://discord.gg/qyBDzFWAaY) and we will revoke the grant server-side. A connected-apps screen is on the roadmap, and this section will be the first thing to change when it lands.

---

## Limits and Gotchas

**Sending a file you have attached to the chat.** The assistant can *look* at an attachment but cannot hand the bytes to X02 — there is no mechanism in the protocol for it, and no AI client exposes your attachments as public links (which is just as well). So instead:

Ask it to upload something, and it gives you a link like `x02.me/drop/K7M2QXR4`. Open it, press **Ctrl+V** if the file is already on your clipboard, and the assistant picks it up and carries on — you never have to go back and tell it you are done. Drop links stay open for fifteen minutes; if you wander off and come back to an expired one, just ask for another.

Better still, **pin `x02.me/drop`** as a tab. Anything you paste in there waits in your tray for twenty-four hours, so if you drop the screenshot *before* you ask, there is no link and no waiting at all.

`upload_file` still exists for genuinely small content — icons, SVGs, short text files. It is comfortable under 128 KB and refuses outright above 1 MB, which a single screenshot already exceeds once base64 has inflated it by a third. When it refuses, it suggests the two routes that do work: upload it yourself on x02.me and tell the assistant what it was called — X02 keeps your original name alongside the short one and `list_files` searches both — or hand over a URL. Ask for a drop link and it will give you one of those too.

`upload_from_url` is the fastest route for anything already online: give the assistant the URL and the bytes never touch the chat. It rehosts **images only** — the URL has to answer with an `image/*` content type, so a PDF or a video link is refused. Private and internal hostnames are refused as well.

**The stored filename is not your filename.** X02 assigns a short name on upload. Assistants are told to use the returned filename for anything afterwards, but if you are cross-referencing by hand, check `list_files` rather than assuming.

**Uploads count against your normal quota.** MCP is not a separate allowance — same daily limits, same plan file-size ceilings. Ask for `get_account` if you are about to run a big batch.

**Uploads land in your default folder.** If you have set one, that is where assistant uploads go too. See [setting a default upload folder](/blog/how-to-set-a-default-upload-folder).

---

## Next Steps & Related Tutorials

| What to learn next | Guide Link |
| :--- | :--- |
| **Step-by-step setup for your client** | [Set Up X02 in Claude, ChatGPT, Cursor and More](/blog/set-up-x02-mcp-in-your-ai-client) |
| **What each permission actually grants** | [X02 MCP Permissions: What You Are Actually Approving](/blog/x02-mcp-permissions-and-scopes-explained) |
| **Getting files in from a chat** | [How to Send Files to X02 From an AI Chat](/blog/how-to-send-files-to-x02-from-an-ai-chat) |
| **Things worth asking for** | [Ten Things to Ask an Assistant Connected to X02](/blog/x02-mcp-workflows-and-recipes) |
| **When something breaks** | [Troubleshooting X02 MCP Connections](/blog/troubleshooting-x02-mcp-connections) |
| **Upload files by every other method** | [How to Upload Files to X02](/blog/how-to-upload-files-to-x02) |
| **Get an API key for your own scripts** | [How to Get an API Key](/blog/how-to-get-an-api-key) |
| **Organize uploads into folders** | [How to Organize Files with Folders](/blog/how-to-organize-files-with-folders) |
| **Set a default upload folder** | [How to Set a Default Upload Folder](/blog/how-to-set-a-default-upload-folder) |
| **Full endpoint reference** | [API Documentation](/api-docs) |