Connecting Your Agent

WitWiki speaks MCP over streamable HTTP at:

https://api.witwiki.app/mcp

Any MCP client that can reach an HTTP server and send an Authorization header can connect. Below are the specific incantations.

Two ways to authenticate

API key (bearer token). You mint a key at /keys, paste it into your client's config, and the server derives the org and project from it. Simple, explicit, and the right default for agents running unattended.

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 can therefore discover the authorisation server on its own and walk you through a browser sign-in — no key to copy, and the resulting credential is tied to your user account rather than to a project.

That last difference bites. An API key is bound to one project; an OAuth session carries your user identity and lands you in whichever project that identity resolves to. If you connect over OAuth and find an unexpectedly empty wiki, you are very likely looking at a different project than the one your bearer key writes to. Troubleshooting covers how to confirm this.

Claude Code

The one-liner, which writes the config for you:

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

Or commit it to the repo so your whole team 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"
      }
    }
  }
}

Don't commit a real key. Most teams keep .mcp.json in .gitignore and check in a .mcp.json.example alongside it.

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

Claude Desktop

Claude Desktop connects to remote HTTP servers through Settings → Connectors → Add custom connector. Give it the /mcp URL above; it will use OAuth discovery where the server offers it, which WitWiki does.

Cursor

Cursor reads the same mcpServers shape from .cursor/mcp.json in your project, or from the global config in Cursor's settings:

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

Any other MCP client

The generic 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. Nothing WitWiki-specific in the protocol.

Verifying

Restart the client so it re-reads its config, then have the agent call wiki_guide. It returns WitWiki's conventions and the tool list, and it is the intended opening call of a session.

A useful second check is wiki_listPages({}). If it returns pages you recognise, your key is pointed where you think it is. If it returns an empty list on a project you know has content, you are authenticated as something else — again, see Troubleshooting.

The guided flow

/connect in the app does all of this for you: mints a key for the active project, renders the config for your client, and flips to Connected the moment your agent's first authenticated call arrives. It's the fastest way to a working setup, and the live confirmation removes the guesswork about whether the config actually took.

Note that the key it mints has no scopes, which means unrestricted access. That's a sensible default for your own agent on your own project; if you want a narrower key, create one at /keys and tick scopes explicitly.

Next