Troubleshooting

Every error the MCP server can return, and what to do about it.

Connection

Unknown tool: wryte_...

The tool was removed in the drafts-only upgrade. Upgrading from the earlier server in the overview lists its replacement. If your client still lists old tools, restart it or reconnect wryte so it fetches the new list.

Protected resource ...\/mcp\/ does not match expected ...\/mcp

The configured URL and the advertised one disagree on the trailing slash. Use the URL exactly as shown in Settings → MCP Server, with no trailing slash:

claude mcp remove wryte
claude mcp add --transport http wryte https://<your-deployment>.convex.site/mcp

The agent never opens a browser

The server isn't advertising a registration endpoint, so the client can't self-register. Confirm discovery resolves:

curl https://<your-deployment>.convex.site/.well-known/oauth-protected-resource/mcp

You should get JSON containing authorization_servers. A 404 means OAuth isn't configured on the deployment.

tools/list is empty and no login is offered

The backend is serving an older build, or every capability is off. Check Settings → MCP Server.

Authorization

No Wryte account for this identity. Sign in at wryte.xyz once, then reconnect.

Your token is valid but no Wryte account matches it. This happens if you authorize an agent before ever signing in through the browser; the account row is created on first web sign-in. Sign in once, then retry. No need to re-authorize.

Forbidden: this capability is not enabled for MCP clients (...)

Exactly what it says: the token is fine, the capability is off. Enable it in Settings → MCP Server. It applies immediately, with no reconnect.

Note this is a 403, not a 401, on purpose: a 401 would make your client throw away a working token and re-run OAuth, which cannot help. The fix is a toggle, not a fresh token.

Media or trash tools aren't in the list at all

Working as designed. Tools you can't call are hidden rather than shown and then refused. Enable the capability and they appear.

During a call

Rate limited: retry in N s (429)

Wait N seconds, then retry. See Rate limits for the budgets and how to reduce round trips.

Tool execution failed

A deliberately generic message. Error text from a tool can quote URLs containing credentials, so anything unexpected is replaced before it reaches the model; specific, user-facing errors are passed through verbatim. The full detail is in the audit log and your Convex logs.

A write is rejected for invalid frontmatter

Your project defines a frontmatter schema and the document doesn't satisfy it. Have the agent read wryte://project/{projectId}/frontmatter-schema first. See Resources.

A status value is rejected

Board statuses are per-project. Read wryte://project/{projectId}/board-columns for the valid set.

Losing work

An agent trashed something

Recoverable. Use wryte_trash_restore, or the trash view in the app. There is no permanent delete over MCP at any capability.

An agent and the editor both edited one document

They can't. Agents only write draft tabs, never the Main version, so your editor and an agent never write the same text. Two agents writing the same draft tab: last write wins.