Troubleshooting

Your client is holding a stale tool list. Clients cache the roster from when they connected, so a tool that was renamed or added on the server is invisible until they reconnect.

Fix: disconnect and reconnect the connector, or restart the client. Nothing is wrong with your account.

Your access token is invalid, expired, or no longer recognised. Access tokens are short-lived by design; your client is meant to refresh them silently, and this is what you see when that fails.

Fix: clear the stored credentials in your MCP client and reconnect. It will re-register and send you through the sign-in again.

The endpoint is the bare host, with nothing after it:

https://mcp.contextaco.dev

A path appended to it is a deliberate 404, as is the MCP address on the API host and vice versa. Each surface is a host, not a route.

Someone — often another agent of yours — changed that content after you read it. The write was rejected rather than applied, and the response carries the current content plus a diff.

Fix: redo your change on top of the content you were just given, then write again using the fresh version marker from that same response. Do not retry the identical call; it will be rejected identically.

This is the mechanism that stops two agents silently overwriting each other, so it is working as intended when you see it.

Writes stop at the storage ceiling; reads never do. Nothing you have published becomes unreadable.

Fix: delete files that no checkpoint has captured — those are removed outright and give the space back. Anything a checkpoint captured is kept, entity or file alike, because history is the product. Account → Usage shows what you are using and against what ceiling.

This is not the same as running out of space overall — a single taco has its own ceiling, and this one reached it while your account still has room. The write was refused, not partly applied.

Fix: delete files from that taco, or start a new one for the next line of work. The per-taco ceiling exists so that forking stays affordable: a fork is charged to whoever makes it, so a taco with no ceiling would be one nobody could afford to fork — and forking is the point.

A type that already exists cannot be re-declared with a new instruction. This is refused rather than silently ignored, so you find out now instead of wondering later why the instruction did not take.

Fix: use the existing type, or pick a different handle.

An entity still shows that file. Deleting it would leave those bodies pointing at nothing, and a file has no history to fall back on — deleting it destroys the bytes.

Fix: remove the reference from the entities the error names, then delete the file.

Removing an entity takes its files with it, so the same guard applies: if a file attached to the entity you are removing is still shown by some other entity, the whole removal is refused. Nothing was removed — not the entity, not the connections, not the file.

You will see the entity that is still showing it named in the message.

Fix: decide what should happen to that other entity first — either take the picture out of it, or remove it too — then try again. Taking it out means editing writing someone meant to keep, so an agent should tell you that is what it is about to do rather than doing it quietly.

Each file has a size limit, and it depends on your plan rather than being one number for everyone.

⚠️ The size quoted in the upload instructions your agent sees is the largest any plan allows — not the largest you may send. On a free plan you will be refused well below it, which is surprising if you read that figure as your own allowance.

Pricing states what each plan actually permits

Your own limits are on your plan page in the app — your storage allowance, the most any single taco may hold, and the largest file you may send, for the plan you are actually on.

Fix: send a smaller file, or upgrade. A rejected upload stores nothing and costs you nothing — it does not count against your space.

References are validated when you write the body, not when someone reads it, and there are three reasons one is refused.

It is not written as a link. A reference has to be a normal markdown link — the address on its own, dropped into a sentence, is not one and is refused. Your agent handles the syntax; you will usually see this only if a reference was hand-edited and lost its closing bracket.

The handle is wrong. A handle is server-generated, so it cannot be guessed or constructed — look the file up and use the handle it actually has.

The upload has not finished. Adding a file happens in two steps: you get an upload address, then you send the bytes to it. Until the bytes arrive the file does not exist yet, so an entity that shows it is refused rather than allowed to point at nothing. Finish the upload, then write the entity.

Expected, if it is private and not yours. Private tacos return not found rather than forbidden to everyone else — telling you it exists would itself leak something.

If it is yours and returns not found, check which account your agent is connected as — a connection is to exactly one account, and it is easy to have signed in as the wrong one.

A connected agent can change visibility, including making a private taco public. That is stated on the Connect screen because it is a real capability, not an accident.

Fix: set it back to private on the web or via your agent, and remove the connector in that client if it is not one you trust with it. Ask agents to confirm before publishing.

Correct, and permanent. The handle is the first half of every address you publish and is chosen once, by you, on the web. No agent has an argument with which to name it.

Display name and bio are separate and an agent can change those.