Connect Claude Code to a shared wiki over MCP

WitWiki is an MCP server at https://api.witwiki.app/mcp. Mint an API key at /connect — it renders this config for you and turns green when the first call lands — or paste it yourself:

claude mcp add --transport http witwiki https://api.witwiki.app/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Or commit it to the repo so the whole team's Claude Code picks it up — .mcp.json at the project root:

{
  "mcpServers": {
    "witwiki": {
      "type": "http",
      "url": "https://api.witwiki.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Never commit a real key. You don't have to: Claude Code expands ${VAR} inside .mcp.json, headers included, so the file you check in carries a reference instead of a credential.

{
  "mcpServers": {
    "witwiki": {
      "type": "http",
      "url": "https://api.witwiki.app/mcp",
      "headers": {
        "Authorization": "Bearer ${WITWIKI_API_KEY}"
      }
    }
  }
}

Each person exports WITWIKI_API_KEY in their own shell, and the file itself is safe to commit. That is worth doing for a second reason: when a teammate opens Claude Code in a repo with a .mcp.json in it, Claude Code asks them whether to trust the server — so checking the file in is what puts the wiki in front of the rest of your team, instead of each person setting it up alone. If the variable is unset, Claude Code names the missing variable rather than failing silently.

Confirm with /mcp inside a Claude Code session — witwiki should be listed as connected.

Check you are in the right project

Ask the agent to call wiki_getIndex. The result names the project it came from (project: {slug, name}), every project is seeded with a starter page, and that page coming back proves the key, the project routing and the tools all work. An empty index means you connected with a different credential than the one that owns your pages: an API key is bound to one project, while Claude Desktop's OAuth connector resolves to your user account and whichever project that lands in. The two can look at two different wikis and each look correct. Troubleshooting shows how to tell which you are on.

Claude Desktop

Claude Desktop connects to remote HTTP servers through Settings → Connectors → Add custom connector. Give it the /mcp URL above; it uses OAuth discovery, which WitWiki offers — you sign in in the browser and no key is copied. The credential is tied to your account, not a project, which is the empty-index case above; run the check.

Cursor

Cursor reads the same mcpServers shape from .cursor/mcp.json in your project, or from the global config in Cursor's settings — the JSON block above, unchanged. We have not verified this on a design partner's machine yet; if it works for you, or does not, tell us and this line changes.

Any other MCP client

The JSON above is the whole contract: an HTTP transport pointed at /mcp with a bearer token. Clients differ only in where that block lives and what they call it. If yours accepts a URL and a header, it will work. For a hand-rolled client, the server is a standard streamable-HTTP MCP endpoint — initialise, list tools, call tools — and the initialize reply carries the three-line contract for changing pages safely.

Two ways to authenticate

API key (bearer token). You mint a key at /keys or /connect, paste it into your client's config, and the server derives the organisation and project from it. Simple, explicit, and the right default for agents running unattended. A key minted on /connect has no scopes, which means unrestricted access — sensible for your own agent on your own project; for a narrower key, create one at /keys and tick scopes explicitly.

OAuth. The server implements RFC 9728 protected-resource metadata and dynamic client registration, and returns a WWW-Authenticate header advertising its metadata URL on a 401. An OAuth-aware MCP client discovers the authorisation server on its own and walks you through a browser sign-in. The resulting credential is tied to your user account rather than to a project.

Verifying

Restart the client so it re-reads its config, then have the agent call wiki_getBrief with a task from your own work, say "how is this service deployed". One call returns the pages worth reading, each with its version and its age; on a wiki that is still empty it returns the starter page and a note. That is the opening call of every task. wiki_guide returns the conventions and the tool list; call it once. Then wiki_getIndex, as above, if you want the map. If the tools do not appear at all, see MCP server not showing up in Claude Code; for a 401, 401 Unauthorized from the MCP server.

Next