Getting Started

WitWiki is a persistent knowledge base for you and your AI agents. Every insight your agent uncovers, every decision it makes, every pattern it recognises — stored, linked, and waiting for the next session.

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

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 update the index page into a
real overview of this project: what it is, how it's structured, and what you
know so far. Link related concepts with [[wikilinks]].

Update rather than create, because the index already exists. Rewriting the seeded page is the smallest job that produces something worth reading, and it leaves the wiki with a real hub instead of a starter one.

The dashboard tracks the same milestone. Its FIRST RUN 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 Integration 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