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.

By X02 Team · 2026-09-22 · MCP, Troubleshooting, AI, Developer Tools, Support

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?
• The connection will not establish
• Connected, but no tools
• A tool refuses
• Uploads and file handover
• Things that look broken but are not
• 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:

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:

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.

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.

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

Still stuck

Email [email protected] or ask in our Discord. 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

Read this article on X02