# Troubleshooting X02 MCP Connections

> Every way an X02 MCP connection fails, what the error actually means, and the fix — from empty tool lists and stale sign-ins to scope refusals, expired drop links and uploads that will not go through.

Source: https://x02.me/blog/troubleshooting-x02-mcp-connections · 2026-09-22 · X02 Team

Most MCP failures surface as something unhelpfully vague — "the connector could not be reached", or an assistant that cheerfully claims it has no X02 tools. This page maps the symptom you can see to the cause underneath.

> [!TIP]
> **Quick Navigation:**
> * [Start here: is it X02 or your client?](#start-here-is-it-x02-or-your-client)
> * [The connection will not establish](#the-connection-will-not-establish)
> * [Connected, but no tools](#connected-but-no-tools)
> * [A tool refuses](#a-tool-refuses)
> * [Uploads and file handover](#uploads-and-file-handover)
> * [Things that look broken but are not](#things-that-look-broken-but-are-not)
> * [Next Steps & Related Tutorials](#next-steps--related-tutorials)

---

## Start here: is it X02 or your client?

Two commands settle it in under a minute.

**Is the server up?** This should return JSON listing the six scopes:

```bash
curl https://up.x02.me/.well-known/oauth-protected-resource/mcp
```

**Does the handshake work?** The official inspector walks each step and shows you where it stops, instead of collapsing everything into one failure:

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

Point it at `https://up.x02.me/mcp`. If the inspector connects and your assistant does not, the problem is the client's configuration — which narrows things down considerably, and is the answer more often than not.

---

## The connection will not establish

**"Could not connect" / "server unreachable", and the URL is right.**
Check the transport. Some clients ask you to choose one when adding a server — X02 needs **HTTP** or **Streamable HTTP**, not stdio. Stdio is for MCP servers that run as a local program on your machine; X02 is hosted, so there is no process to launch.

**There is no "Add custom connector" option at all.**
Plan or policy, depending on the client.

| Client | Requirement |
|---|---|
| Claude, personal plans | Available on all plans |
| Claude, Team and Enterprise | An organization owner adds it under Organization settings → Connectors; members then connect their own account |
| ChatGPT | A paid plan (Plus, Pro, Business, Enterprise or Edu). Not on Free, and not in the mobile apps |
| ChatGPT, Business and Enterprise | An admin may need to allow developer mode first |

In ChatGPT the toggle is also one level deeper than most guides say: **Settings → Apps & Connectors → Advanced settings → Developer mode**.

**Sign-in opens, but nothing happens after I approve.**
Usually one of two things. Either the browser blocked the redirect back to the app, or the authorization request expired — they last **ten minutes**, and a stale one fails quietly rather than saying so. Start the connection again from the client and complete it promptly.

**I am not sure the consent screen is legitimate.**
Look at the redirect host it shows you. Any developer can register a client and name it anything, "X02 Official" included — the name is self-declared and proves nothing. The redirect destination is checked. If that host is not the app you just clicked in, deny it.

---

## Connected, but no tools

**The connector shows as connected and the assistant says it has none.**

Almost always a cached tool list. Clients fetch the tool list when they first connect and hold onto it. Disconnect the connector and reconnect it — restarting the app alone often is not enough.

This is also what to do after X02 ships new tools. Your client keeps the list it fetched originally, so new capabilities stay invisible until it re-handshakes.

**How to confirm it is actually working.** Ask:

> "What x02 tools do you have?"

You are looking for **fifteen**. Then the real test, which exercises the connection, the permissions and a write in one go:

> "Upload https://x02.me/favicon.ico to my account and give me the link."

---

## A tool refuses

**"This app was not granted the *files:delete* permission."**

Exactly what it says: the connection was approved without that scope. Reconnect the app and approve it. Note that the message names the scope the *tool* needs, which is not always the one you would guess — deleting a folder needs `folders:write`, not `files:delete`. The full mapping is in [the permissions guide](/blog/x02-mcp-permissions-and-scopes-explained).

**Everything worked, and now every call fails.**

If this happened suddenly and reconnecting fixes it, the likely cause is refresh token reuse detection. X02 rotates refresh tokens, and if a retired one is presented again — two copies of a client running against the same stored credential, usually — the whole grant is revoked on the assumption the token was copied. Reconnecting issues a fresh one.

**A 401 with a `WWW-Authenticate` header.**

Normal, and not an error you need to act on. It is how the server tells a client where to find its metadata on the first request, before any token exists. If you are watching network traffic during setup you will see exactly one.

---

## Uploads and file handover

**"I cannot upload the file you attached."**

Expected. An assistant can look at an attachment but has no way to pass the bytes to a remote server — a gap in the protocol, not a misconfiguration. Ask it to upload anyway and it hands you a drop link.

**The drop link expired.**

They stay open **fifteen minutes**. Ask for another; nothing is lost. Better, paste files into your tray at [x02.me/drop](https://x02.me/drop) before you ask — a tray drop waits twenty-four hours and goes to whichever assistant asks next.

**The assistant keeps saying "not dropped yet".**

That is the expected in-between state, not a failure. It polls in roughly ten-second stretches, so a couple of "waiting" results while you find the file are normal. If several pass with nothing, check you actually opened the link — the assistant cannot tell the difference between a page you never opened and one you are still using.

**I use two assistants and one cannot see the other's file.**

Working as intended. A file handed over through a drop link is delivered to the app that requested it, and to no other. Use the tray if you want something available to whichever assistant asks next.

**"Only image URLs are supported."**

`upload_from_url` rehosts images only — the URL has to answer with an `image/*` content type. A PDF, video or HTML page is refused. Use a drop link for those instead.

**The upload is refused as too large.**

Two different ceilings, depending on the route. `upload_file` carries bytes inline through the conversation and refuses above **1 MB** (comfortable under 128 KB) — base64 inflates by a third, so even a modest screenshot exceeds it. Drop links and URL rehosting use your plan's real limit: 80 MB anonymous, 200 MB registered, 512 MB on Pro.

**"You have reached your daily upload limit."**

MCP shares your normal quota — 250 uploads a day on a registered account, 1,500 on Pro. Ask `get_account` before a batch: "how many uploads do I have left today?"

---

## Things that look broken but are not

**The uploaded file has a name I did not choose.** X02 generates a short stored name on upload. That is the one every other tool expects. Your original name is kept alongside it and `list_files` searches both, so you can still find it by the name it had on your machine.

**A search returned something unrelated.** Search is fuzzy by design. Results are labelled `[exact match]` or `[fuzzy match]`, and a fuzzy match may not contain your term at all. Ask the assistant to list what it found rather than trusting a single confident answer.

**`view_file` says there is nothing to show.** It only previews images. PDFs, videos and archives have no thumbnail — `get_file` gives you their details instead.

**Claude connects from Anthropic's servers, not your computer.** Invisible for X02, which is on the public internet. It matters if you ever add a *different* MCP server running on localhost or behind a company VPN — those cannot work this way, however well they run on your machine.

**Uploads went into a folder I did not specify.** Your default upload folder applies to assistant uploads too. See [setting a default upload folder](/blog/how-to-set-a-default-upload-folder).

---

## Still stuck

Email [contact@x02.me](mailto:contact@x02.me) or ask in [our Discord](https://discord.gg/qyBDzFWAaY). The two things worth including: which client you are using, and whether `npx @modelcontextprotocol/inspector` can connect to `https://up.x02.me/mcp`. That second answer tells us which half of the problem to look at.

---

## 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 MCP is and what it can do** | [Connect AI Assistants to X02 with MCP](/blog/connect-ai-assistants-to-x02-with-mcp) |
| **What each permission 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 to ask your assistant** | [Ten Things to Ask an Assistant Connected to X02](/blog/x02-mcp-workflows-and-recipes) |
| **Full endpoint reference** | [API Documentation](/api-docs) |