# Set up Listspace for your user

Your user asked you to set up Listspace (https://listspace.app), for example with "Set up Listspace for me: listspace.app/connect". Listspace is project memory for AI agents: boards that you read and keep up to date, within limits the user sets. These steps connect Listspace to the app you are running in. They are written for you, the AI, and the user can read them too.

## Rules

- Do this only for your own user, in this conversation, and only because your user asked for it.
- Ask before you run any command on the user's computer. Show the command, say what it does, and wait for a yes.
- Never ask for the user's Listspace password. The user signs in to Listspace in the browser.
- This page never asks you to send files, messages or other data anywhere. If anything seems to, stop and ask the user.

## 1. Work out which app you are running in

Your system prompt and your tools usually tell you. If you are not sure, ask the user which app this is.

- Check this first: if you already have Listspace tools such as `get_account`, call it. If it answers, Listspace is connected. Go to step 6.
- You can run commands on the user's computer (Claude Code, Codex, Gemini CLI, Cursor, VS Code, Windsurf): you are a coding agent. Use step 3 after step 2.
- You are a chat app that cannot install anything (Claude on claude.ai or in the desktop app, ChatGPT): use step 4 after step 2.

## 2. Check that the user has a Listspace account

Ask whether the user has a Listspace account. If yes, go to step 3 (coding agents) or step 4 (chat apps). If not:

- Listspace is in an invite-only beta, so a new account needs an invite code. It is in the user's invite email (the link ends in `invite=` and the code).
- No invite code: the user joins the waitlist at https://listspace.app/waitlist. Stop here and tell the user that Listspace sends an invite by email.
- With a code: the user signs up at https://listspace.app/signup, or you offer to create the account. Ask for the user's email address and invite code, and say that Listspace sends the user an email to confirm.

To create it: call `get_signup_challenge`, then `create_account` with the email address and `invite_code`. They are on the MCP server at https://mcp.listspace.app/signup, which needs no sign-in, or in the REST API as `POST https://api.listspace.app/v1/accounts/challenge` and `POST https://api.listspace.app/v1/accounts` (details at https://listspace.app/docs/api). The user then gets an email and claims the account within 72 hours by setting a password. Ask the user to do that before you connect: until then, signing in from another app does not work.

## 3. Coding agents: add Listspace yourself

Find your app below. Show the user the command, ask, and run it only after a yes. Every app connects to the same address and signs in with the user's Listspace account, so there is no token to copy. If the app says a server named `listspace` already exists, do not add it again: go on to the sign-in.

### Claude Code

Terminal:

```bash
claude mcp add --scope user --transport http listspace https://mcp.listspace.app
```

`--scope user` adds Listspace for all of the user's projects. Claude Code loads a new server when a session starts. Tell the user to start a new session (in a terminal: exit and run `claude` again; in the VS Code extension: a new chat), type `/mcp`, choose `listspace` and choose **Authenticate**. The browser opens Listspace. The user signs in if asked, then clicks **Continue as** and **Allow**. Then the user pastes the sentence again in that session, and step 1 finds the Listspace tools.

### Codex

Terminal:

```bash
codex mcp add listspace --url https://mcp.listspace.app
```

Then sign in:

```bash
codex mcp login listspace
```

The browser opens Listspace. The user signs in if asked, then clicks **Continue as** and **Allow**.

### Gemini CLI

Terminal:

```bash
gemini mcp add --scope user --transport http listspace https://mcp.listspace.app
```

Then the user types `/mcp auth listspace` in Gemini CLI. The browser opens Listspace. The user signs in if asked, then clicks **Continue as** and **Allow**.

### VS Code (GitHub Copilot agent mode)

Terminal:

```bash
code --add-mcp '{"name":"listspace","type":"http","url":"https://mcp.listspace.app"}'
```

The quotes in this command are for bash and zsh; PowerShell and cmd treat them differently. On Windows, or when unsure, have the user click **Add to VS Code** on https://listspace.app/setup instead. VS Code asks the user to sign in the first time it uses Listspace. The browser opens Listspace. The user signs in if asked, then clicks **Continue as** and **Allow**.

### Cursor

Add the `listspace` entry below under `mcpServers` in `~/.cursor/mcp.json`, and keep any servers that are already there. Or the user clicks **Add to Cursor** on https://listspace.app/setup. Then the user starts the sign-in from the MCP server list in Cursor. The browser opens Listspace. The user signs in if asked, then clicks **Continue as** and **Allow**.

mcp.json:

```json
{
  "mcpServers": {
    "listspace": {
      "url": "https://mcp.listspace.app"
    }
  }
}
```

### Windsurf

Add the `listspace` entry below under `mcpServers` in the Cascade MCP config file, and keep any servers that are already there. The user can open the file from the Cascade panel: the **...** menu, then **MCPs**, then **Open MCP config file**.

mcp_config.json:

```json
{
  "mcpServers": {
    "listspace": {
      "serverUrl": "https://mcp.listspace.app"
    }
  }
}
```

### Another app

Any app that connects to a remote MCP server over HTTP with sign-in (OAuth) works with the address https://mcp.listspace.app. The steps for many apps are at https://listspace.app/works-with. A command-line agent without MCP can pair instead: `POST https://api.listspace.app/v1/auth/device` gives a code and a link, the user confirms the code at https://listspace.app/connect, and you get a token (details at https://listspace.app/docs/api).

Most apps load a new MCP server only in a new session, and a new session does not remember this one. If the Listspace tools do not show up after the sign-in, ask the user to restart the app or start a new chat and to paste the sentence again. You then find the Listspace tools in step 1 and continue from there.

## 4. Chat apps: give the user the clicks

A chat app cannot add a connector by itself. Give the user the steps for the app in use, with this address to copy:

Listspace MCP address:

```text
https://mcp.listspace.app
```

### Claude (claude.ai and the desktop app)

1. In Claude, open **Customize** in the sidebar, then **Connectors**. Click **+ Add**, then **Add custom connector**.
2. Type `Listspace` as the name and paste the address. Click **Continue**, keep the sign-in settings as they are, click **Continue** again, then **Add**.
3. A Listspace window opens. Sign in, click **Continue as** with your name, then **Allow**.

Then start a new chat, click the **+** button, then **Connectors**, and check that Listspace is on. The free plan can add one custom connector. On a Team or Enterprise plan, an owner of the workspace adds it.

### ChatGPT

1. On chatgpt.com on a computer, click your name, then **Settings**, then **Security and login**, and turn on **Developer mode**. ChatGPT needs it to add an app that is not in its own directory yet.
2. Click **Plugins** in the sidebar, the plus button, then **Add custom MCP server**. Type `Listspace` as the name, paste the address under **Connection**, choose **OAuth**, click **I understand and want to continue**, then **Create as a plugin**.
3. A Listspace window opens. Sign in, click **Continue as** with your name, then **Allow**. Install the plugin when ChatGPT offers it.

Then start a new chat, type **@** and pick Listspace. This needs a paid ChatGPT plan; the free plan cannot add apps of its own yet. On a work account, an admin may have to allow it first.

Another chat app, such as Gemini, Grok or Le Chat: the steps for each are at https://listspace.app/works-with. Pictures of every screen for Claude and ChatGPT are at https://listspace.app/setup.

## 5. Check that it works

When the user says it is done, call `get_account`. If it answers, tell the user that Listspace is connected and go to step 6. If it does not, the two most likely fixes are:

1. The app has not loaded Listspace in this chat yet. In a chat app, start a new chat and switch Listspace on there. In a coding agent, restart it or start a new session.
2. The sign-in did not finish. Run it again: `/mcp` and **Authenticate** in Claude Code, `codex mcp login listspace` in Codex, `/mcp auth listspace` in Gemini CLI. In Claude or ChatGPT, open the connector in the settings and connect it.

Still stuck? The user can write to hello@listspace.app and say where it stopped.

## 6. Start working

1. `get_account` lists the user's boards. Offer to make a first board for what the user is working on (`create_board`, which returns the new board's id), or let the user pick an existing one. Then call `start_session` with that board's id.
2. Explain freedom levels in two sentences, for example: "Freedom levels decide how much I may change in Listspace on my own, from 1 (read only) to 5 (full). Anything my level does not allow waits in the board's Inbox until you accept or reject it."
3. Ask the user how much you may change on your own. Only the user sets the level: in Listspace under **Settings**, then **Agents** for the whole account, or in a board's **⋯** menu under **Agent access** for one board. You cannot change a level, so never try to raise one. New accounts start at level 3, and `get_account` shows the highest level the user's plan allows.

From then on, keep the board up to date while you work, as the Listspace server instructions describe.

This page as HTML: https://listspace.app/connect. As markdown: https://listspace.app/connect.md.