Troubleshooting WitWiki: connection, 401, 403, empty wiki
Ordered roughly by how often each one happens.
The MCP tools don't appear at all
The client never completed a handshake — a config problem, not an auth one. The four checks, in order, are on MCP server not showing up in Claude Code.
401 Unauthorized
The credential wasn't accepted — or, from an OAuth-aware client, the discovery handshake is doing its job. Both on 401 Unauthorized from the MCP server.
403 Forbidden
Authenticated fine, not allowed to do that. There are two separate systems that produce a 403, and knowing which one fired tells you the fix.
Missing scope — the message names the scope, e.g.
missing scope: wiki:write. Your API key doesn't carry it. Mint a key with the
scope, or with no scopes at all (which means unrestricted).
Insufficient role — the message is insufficient role. Your account's role
in the org is too low. Roles rank owner 50, admin 40, member 30,
viewer 20, agent 10, and each endpoint requires a minimum.
The most common surprises:
| Operation | Needs | Catches out |
|---|---|---|
DELETE /api/pages/{path} | admin | Members can create pages but not delete them |
| Deleting a page over MCP | wiki:write scope | Same action, different gate — MCP never checks role |
GET /api/org/members | viewer | An agent-role API key cannot list the org's members |
POST /api/graph/rebuild | member | It rewrites derived state, so it is an editor action |
PATCH/DELETE /api/org/members/{userID} | admin | And only for members below your own rank — see below |
GET /api/audit | owner | Admins cannot read the audit log |
| Billing | owner | Not delegable; promote a second owner instead |
Role changes and removals that get refused
Roles are editable in /settings, and removal follows the same rules — deleting a member is the same privilege as demoting them. Four messages produce a 403 or 409 rather than a saved change:
- "You cannot assign a role at or above your own level." An admin can move
someone between
memberandviewer; making another admin, or touching an owner, is an owner's job. - "You cannot change the role of / remove a member at or above your own level." Admins cannot demote or delete owners and fellow admins.
- "You cannot change your own role." Nobody can, owner included, and nobody removes themselves. Promote a second owner and have them demote you.
- "Org must retain at least one owner." The last owner can be neither demoted nor removed — billing, the audit log, and org settings would have nobody who could reach them.
Why MCP and REST disagree
The REST API enforces roles. MCP enforces scopes. They are independent, so the same credential can succeed over one surface and fail over the other.
The clearest case is page deletion. Over MCP, an agent-role key with
wiki:write deletes pages without complaint. Over REST, the identical key hits
DELETE /api/pages/{path} — which demands rank 40 — and agent ranks 10. It
gets a 403.
This is deliberate. MCP is the agent surface and scopes are the agent control; REST is the human surface and roles are the human control. When a permission result surprises you, first work out which surface you were on.
My wiki is empty, but I know I wrote pages
Almost always identity or project, not data loss. Ask which credential am I using, and which project does it resolve to?
- API keys are bound to one project. A key issued for project A will never see project B's pages, no matter which project the web UI is showing.
- OAuth resolves to your user account, not to a project. Connecting the same wiki over a bearer key and over OAuth can very easily land you in two different projects — and each will look correct and empty from the other's point of view.
- The web app shows the active project, chosen in the top-nav selector. It is not necessarily the project your key writes to.
Confirm it directly:
project_list({}) → which projects can this credential see?
wiki_listPages({}) → what does it actually hold?
If wiki_listPages returns content you don't recognise, you're authenticated as
something other than you assumed. Mint a key for the project you actually want.
wiki_getIndex returns "not found"
Every project is seeded with an index page at creation, so this should not
happen on a new project — if it does, you are almost certainly pointed at a
different project than you think (see above), or the index was deleted at some
point. wiki_updateIndex recreates it.
My agent has the tools but never uses them
Not a bug — a prompting gap. A connected agent has no reason to believe the wiki contains anything useful and no instruction to write to it.
Paste the CLAUDE.md or AGENTS.md snippet from Teaching your agent into your repo. That's the piece that turns a connection into a habit.
My agent overwrote a page
Nothing is lost — History and Restore put it back — and the prompt is the fix. The whole of it is on My agent overwrote a wiki page.
Everything works, but writes fail with a scope error
You created the key with scopes ticked and wiki:write isn't among them.
Worth knowing which direction the default runs: an empty scope list means unrestricted, not read-only. A key created with no boxes ticked can do everything. Restricting a key requires ticking scopes deliberately — and once you tick any, only what you ticked is permitted.
Still stuck
Check /log for what your agent actually did, and /audit (owner-only) for authentication and permission events. Between them they usually show which identity made the call and what the server thought of it.