Getting started with WitWiki: connect an agent in ten minutes

WitWiki is a wiki your team and your coding agents write to at the same time — agents over MCP, people in the browser, both editing the same pages. Every write carries a scoped key, the name of whoever made it, an audit entry, and a version you can go back to.

This page takes you from nothing to a connected agent. It should take about five minutes.

The fastest path is /connect, which walks you through the steps below and confirms the handshake live. The rest of this page is the same thing by hand.

1. Create an account and a project

Sign up at witwiki.app, then create your first project from the dashboard.

A project is an isolated knowledge base. Pages, sources, and log entries all belong to exactly one project, and an API key is bound to one project — so name each project after the thing it holds knowledge about, usually a codebase or a product area.

Start with one. You can add more later from /projects, and switch between them with the selector in the top nav.

Every new project is born with a single seeded index page — a starter hub written for both you and your agent, and the thing your agent's first job will be to replace.

2. Generate an API key

Go to /keys and create a new key.

Copy the key immediately. It is shown exactly once and stored only as a bcrypt hash — if you lose it, you revoke it and issue a new one. There is no way to recover the original value.

Two things to decide when you create it:

  • Which project. The key carries its project with it. Your agent never passes a project ID — the server derives it from the key.

  • Scopes. Four are available: wiki:read, wiki:write, source:read, source:write. Read operations require no scope at all; wiki:write gates page and log writes, and source:write gates source changes.

    Selecting no scopes grants full access, not read-only access. An empty scope list means unrestricted, which is the opposite of what the blank checkboxes suggest. To make a key that can read but not write, tick wiki:read and source:read explicitly.

3. Connect your agent

The fastest path is /connect, which walks you through it and confirms the handshake once your agent calls in.

To do it by hand, add this to your project's .mcp.json (or your MCP client's equivalent config):

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

Replace YOUR_API_KEY with the key from step 2. Client-specific instructions — Claude Code, Claude Desktop, Cursor, and anything speaking MCP over HTTP — are on Connecting Your Agent.

4. Verify the connection

Restart your MCP client so it picks up the new config, then ask your agent to call wiki_guide. It returns WitWiki's conventions and the tool list, and it is the intended first call of any session.

If that works, try wiki_getIndex. It returns the seeded starter page described in step 1 — that page coming back is the confirmation that authentication and project routing are both working.

If the tools don't appear at all, or you get a 401 or 403, see Troubleshooting.

5. Give your agent its first job

Authenticating is not the same as using it. The first real write is what turns an empty project into a wiki, so /connect reveals a third step the moment the handshake lands: a copy-paste prompt, and a live indicator that flips to First edit ✓ — with a link to the page — as soon as your agent writes.

The prompt it hands you:

Call wiki_guide to learn the conventions. Then read CLAUDE.md and AGENTS.md in this repo and split them into one wiki page per topic under concepts/, architecture/ and guides/, cross-linking related pages with [[wikilinks]]. Rewrite the index page to link every page you made, then run wiki_lint and fix anything it reports.

Your CLAUDE.md already holds what a new teammate needs to know; splitting it into linked pages is the smallest job that produces something worth reading, and it leaves the wiki with a real hub instead of a starter one. Your first hour walks through what to do once it lands.

The dashboard tracks the same milestone. Its Getting started checklist stays up until your agent is connected, has made that first edit, has linked two pages together, and has ingested a source — then it retires itself.

6. Teach your agent when to use it

A connected agent has the tools but no instinct for reaching for them. Without a prompt telling it when to read and when to write, it will mostly ignore the wiki.

Paste the CLAUDE.md or AGENTS.md snippet from Teaching your agent into your repo. That snippet is what turns the connection into a habit — check the wiki at session start, write back what was learned at the end.

Where to go next