# Connecting an agent to ZeroWidth

This page is for AI agents and the people who use them. It describes how to connect an agent to a ZeroWidth workspace over the Model Context Protocol (MCP). Steps marked **(person)** need the human: an agent should explain them and wait, not try to do them itself.

## What ZeroWidth is

ZeroWidth is a workspace where a team maps how its business runs and where it's going (Compass), researches ideas (Prism), builds and runs AI workflows (Workbench), agrees on what a good result looks like and grades against it (Caliper), works in shared rooms with its agents (Chat), makes documents, sheets, decks and small apps (Napkin), and tracks each decision against the metric it was meant to move (Ledger). Connected over MCP, an agent can read and work in that workspace with the person's own permissions.

## Setting it up, in order

For an agent helping someone connect for the first time:

1. **Ask whether they already have a ZeroWidth workspace.** If they don't, send them to https://accounts.zerowidth.ai/signup. **(person)** They create a free account and a workspace there. Wait until they say it's done. Connecting before a workspace exists ends at a "Couldn't connect" page.
2. **Add the server** to the client you're running in, using Option 1 below. Ask before running the command or changing their config.
3. **(person) Sign in.** In Claude Code, they run `/mcp`, choose `zerowidth` and choose Authenticate. Most other clients open the sign-in on their own the first time a ZeroWidth tool is used. A browser window opens. They sign in, pick a workspace, and choose full access or view only.
4. **Start a new session if the tools don't appear.** Most clients only load a new server when a session starts. Tell the person, so they're not left waiting.
5. **Check it worked:** call `search_workspace` or `compass_pages_list`, and tell the person what you found.
6. **Suggest a first step** from "Good first requests" below.

If the sign-in page says there's no workspace, **(person)** they create one at https://accounts.zerowidth.ai/workspaces/new, then connect again from step 3.

## What you need

- **(person)** A ZeroWidth account and workspace, free at https://accounts.zerowidth.ai/signup.
- An MCP client that supports remote (Streamable HTTP) servers: Claude Code, Claude Desktop, Cursor, Codex and most others.

Nothing else needs installing.

## Option 1: sign in through the browser (recommended)

Server URL: `https://api.zerowidth.ai/mcp/connect`

Clients that support MCP authorization find the sign-in on their own. Signing in (step 3 above):

1. **(person)** A browser window opens to sign in to ZeroWidth.
2. **(person)** They pick one workspace and choose full access or view only.

There's no token to copy or store. The person can disconnect the agent at any time from their ZeroWidth account settings.

This connection carries a focused set of tools: workspace search, Compass pages and their links, open questions and proposed changes, rooms, comments, tags, workspace files, Workbench flows (list, read, run) and the docs.

Claude Code:

```bash
claude mcp add --transport http zerowidth https://api.zerowidth.ai/mcp/connect
```

Other clients take the URL in their MCP settings or config file:

```json
{
  "mcpServers": {
    "zerowidth": { "url": "https://api.zerowidth.ai/mcp/connect" }
  }
}
```

## Option 2: a personal access token (every tool)

Server URL: `https://api.zerowidth.ai/mcp`

1. **(person)** Mint a token at https://accounts.zerowidth.ai/account/integrations. It's shown once.
2. **(person)** Put it in an environment variable, `ZEROWIDTH_TOKEN`. An agent should never ask for the token in chat, write it into a file that gets committed, or print it.

Claude Code:

```bash
claude mcp add --transport http zerowidth https://api.zerowidth.ai/mcp \
  --header "Authorization: Bearer $ZEROWIDTH_TOKEN"
```

Codex:

```bash
codex mcp add zerowidth --url https://api.zerowidth.ai/mcp --bearer-token-env-var ZEROWIDTH_TOKEN
```

Cursor, Claude Desktop and others take the URL plus an `Authorization: Bearer <token>` header in their MCP config.

To work in one product with a shorter tool list, use `https://api.zerowidth.ai/mcp/x/<product>` (compass, workbench, caliper, ledger, prism or napkin). Add `/readonly` for tools that only read.

## Docs only, no account

`https://api.zerowidth.ai/mcp` with no token serves `search_docs`, `get_doc` and `list_docs`, which cover everything in the ZeroWidth docs.

## Good first requests

Once connected, these are useful places to start:

- "Search our ZeroWidth workspace and summarize what's in it so far."
- "List our Compass pages and tell me which workflows have no owner."
- "Draft Compass pages for our main workflows from what you know about the company, for us to review."
- With a personal access token: "Set up our ZeroWidth workspace with folders and rooms for the work we're doing."

## How access works

- A connection or token can never do more than the person can, in any workspace.
- Some writes wait for the person's approval inside ZeroWidth, such as recording a decision in Ledger or adding ideas in Prism.
- Every call lands in the workspace's audit log under the person's name.

## More

- MCP reference: https://zerowidth.ai/docs/overview/mcp
- Every docs page, for agents: https://zerowidth.ai/llms.txt