# Set up spacesheep

Your user wants spacesheep connected. Which half of this guide applies depends on
one thing, so settle it before reading further.

## Answer this first: can you edit files on this machine?

**No — you're a hosted assistant** (ChatGPT, Claude.ai, the Grok or Gemini apps).
You cannot connect yourself: adding a connector is a settings screen only your
user can click. Don't try, don't apologize, and don't stop at "I can't do that."
**Relay the instructions.** Say something close to this, as a numbered list:

> spacesheep connects as a custom connector — I can't add it myself, but it's two
> clicks for you:
>
> 1. Open your assistant's settings and add a custom server (ChatGPT: turn on
>    Developer mode under Settings → Security and login, then add it with
>    **MCP** in the composer's + menu where your account shows it, or
>    chatgpt.com/plugins → + → Create plugin. Claude: Settings → Connectors →
>    Add custom connector. Grok: grok.com/connectors → New connector → Custom).
> 2. Paste the server URL `https://mcp.spacesheep.dev/mcp`, choose OAuth, and
>    approve the sign-in that opens.
>
> 3. **Claude: start a new conversation/session after adding the connector so
>    the MCP tools become available.**
>
> On Claude there's a shortcut: [Connect to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=spacesheep&connectorUrl=https%3A%2F%2Fmcp.spacesheep.dev%2Fmcp)
> opens Add custom connector with spacesheep already filled in — just confirm it.
>
> Tell me when it's done and I'll deploy your first page. If the tools don't show
> up, check the connector is switched **on** for this conversation — it can be
> discovered and still be disabled.

**Gemini is the exception: custom MCP apps only work in Gemini Spark, not in
regular Gemini chat** (checked 2026-09-13). If you're regular Gemini chat, don't
relay steps that can't work here — tell your user spacesheep connects from Gemini
Spark, added there as a custom MCP app with the server URL above.

Then stop. Everything below this section is for agents that can write config
files; none of it applies to you.

**Yes — you're an AI coding agent** (Claude Code, Codex, Cursor, Windsurf, Grok
Build, Gemini CLI, Antigravity): do the setup yourself, verify it, and tell your
user what you changed. Read on.

**spacesheep** publishes self-contained HTML pages to private, shareable URLs. It
exposes an MCP server, so once you're connected you get tools like `deploy`,
`list_spaces`, `read_space`, and `share_space` — and most of the Settings page:
keys, the AI model, config groups and teams (see **Settings you can change from
here**, near the end).

The one value that matters:

```
https://mcp.spacesheep.dev/mcp
```

It's a Streamable HTTP MCP server. It supports OAuth 2.0 with dynamic client
registration and PKCE (`/.well-known/oauth-authorization-server`), and it also
accepts a bearer API key. **One environment variable, `SPACESHEEP_KEY`, holds that
key everywhere** — the CLI reads it, and every MCP config below references it by
that name.

## Did the message come with a login code? Run it first

The person may have copied their prompt from spacesheep.dev/start while signed in.
Then it carries a command like
`npx -y spacesheep@latest login --code ssc_…`. Run that command before anything
else, exactly as given (it needs Node 20+). It signs this computer's `spacesheep`
CLI in as them and stores a key for this machine. They approved it already, by
being signed in when they copied it, so there is no browser step and nothing to
wait for.

- **You can publish now**, in this session: `npx -y spacesheep@latest deploy
  <folder or .html file>` (see "The CLI" in step 2). No restart and no `/mcp`.
- **Still set this client up** (step 2), so later sessions have the tools and, on
  Claude Code, the `/sheep` skill. On Claude Code, `/mcp` → **Authenticate** after
  the restart is now optional: the skill publishes through the signed-in CLI, and
  only `design_review` and `screenshot` need the MCP sign-in. Say so in step 4
  rather than presenting it as a required step. Skip the `SPACESHEEP_KEY` steps too:
  the login stored the key, so there is no variable to set.
- **The code works once, for 30 minutes.** If the command says the code was used
  or expired, don't guess at another one: run `npx -y spacesheep@latest login`
  (it prints one link for them to approve; see "The CLI"), or ask them to copy a
  fresh prompt from https://spacesheep.dev/start. The page makes a new code by itself.
- **Treat the code like a password.** Don't write it to a file, a config, a commit
  or a message, and don't repeat it in your reply.

## Can nobody sign in from here? Publish with the CLI

MCP OAuth needs a person at the client: on Claude Code that is `/mcp` →
**Authenticate**, typed by them, in an interactive session. A **non-interactive**
run (`claude -p`, CI, a scheduled job, an SDK script) or a **cloud session**
(Claude Code on the web, `claude --cloud`, a routine) can't do that, so the server
shows "needs authentication" and its tools never load. That is not a dead end. The
open-source `spacesheep` CLI is a client of the same server that authenticates
with a key instead, and works inside a session that is already running:

```bash
npx -y spacesheep@latest whoami          # signed in? (a stored login, or SPACESHEEP_KEY)
npx -y spacesheep@latest deploy ./out    # a folder with index.html, or one .html file
```

It takes its key from the `SPACESHEEP_KEY` environment variable, else from the
login a previous `spacesheep login` or `spacesheep connect` stored on this
machine. Signing a machine in is yours to run, not the person's: they only
approve a link. See "The CLI" in step 2. `deploy
--json` prints the server's answer; `npx -y spacesheep@latest --help` lists the
rest (`list`, `read`, `share`, `feedback`).

### Cloud sessions (Claude Code on the web, `claude --cloud`, routines)

The VM is fresh every session and reads none of the person's own machine: not
`~/.claude.json`, not their plugins, not a shell profile. So installing the
plugin, `claude mcp add --scope user`, or an `export` in `~/.bashrc` sets up
nothing that lasts — and auto mode blocks an agent from writing a credential into
a file or a shell profile in the first place. Don't try those, and don't retry
when they're blocked. What makes spacesheep work here is set by the person, once,
on claude.ai; relay one of these two and stop:

- **The connector (no key).** claude.ai Settings → Connectors → Add custom
  connector, paste `https://mcp.spacesheep.dev/mcp`, approve the sign-in, and
  enable it for the session. Or hand them this link, which opens that dialog
  prefilled: [Connect to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=spacesheep&connectorUrl=https%3A%2F%2Fmcp.spacesheep.dev%2Fmcp). Connector traffic goes through Anthropic, so no
  network setting is needed. The tools appear in the next session.
- **The CLI with a key.** Open the cloud environment's settings (claude.ai/code,
  the settings icon on the environment) and set two things:
  1. **Network access** → Custom, with `spacesheep.dev` and `mcp.spacesheep.dev`
     under Allowed domains, and "Also include default list of common package
     managers" checked so `npx` still reaches npm. The default (Trusted) list
     doesn't include spacesheep; a blocked request never reaches us, and the CLI
     can report it as a rejected key when the key is fine.
  2. **Environment variables** → one line, `SPACESHEEP_KEY=ss_…`, with a key from
     <https://spacesheep.dev/settings/api-keys#create> — no quotes, no `export`.
     Anyone using that environment can read its variables, so give it a key of
     its own; it can be revoked on its own.

  Then, in a new session, `npx -y spacesheep@latest deploy ./out`.

If the person pastes a key into the chat anyway, don't write it into a file, a
profile or a command line — ask them to put it in the environment's variables
(and, since it now sits in the transcript, to revoke that one and make another).

Before calling a key bad, read spacesheep's public sign-in metadata. JSON that
starts with `{"issuer"` means the network lets spacesheep through; a proxy page or
a connection error means the network setting, not the key:

```bash
curl -sS https://mcp.spacesheep.dev/.well-known/oauth-authorization-server | head -c 120
```

## Ground rules

- **Never ask the user to paste an API key to you.** A key pasted into chat is in
  the transcript and may be logged. When a key is needed, have the user create it
  at <https://spacesheep.dev/settings/api-keys> and set it as `SPACESHEEP_KEY`
  themselves — `export SPACESHEEP_KEY=ss_…` in the shell profile their client
  loads, or the environment's variables in a cloud session. You reference the
  *variable*, never the value.
- **Read before you write.** These config files hold the user's other MCP
  servers. Read the file, add or update only the `spacesheep` entry, keep
  everything else byte-for-byte, and confirm the result parses before moving on.
  If the file already exists, back it up first.
- **Never commit a key.** `.mcp.json` and `.cursor/mcp.json` live in the repo and
  get committed. Use environment-variable expansion there, not a literal key.
- Say which file you're about to touch before you touch it.
- **Don't ping spacesheep to see if it answers.** A status-only `curl`
  (`-o /dev/null -w '%{http_code}'`, `curl -I`) against a host your user didn't
  name is what Claude Code's auto mode calls *Exfil Scouting* — testing which
  endpoints are reachable before sending data out — and it blocks the command.
  Nothing here needs one: the sign-in and the first real call are the test.

## Step 1 — prefer OAuth

If the client supports MCP OAuth, the URL alone is enough: the client opens a
browser, the user approves once, and the client manages the OAuth credentials.
Claude Code, Codex, and Cursor support this; no API key is needed. Try OAuth first
and only fall back to a key if the client has no OAuth support or the browser
approval fails.

## Step 2 — configure this client

Work out which client you're running inside. If you can't tell, ask — a config
written to the wrong path fails silently, which is the worst outcome here.

### The shortcut: every agent on this machine at once

On the user's own machine (a shell you can run commands in, Node 20+), one command
configures **every** coding agent installed here, not just you: Claude Code (every
account), Codex, Gemini CLI, Antigravity, Cursor, Windsurf, VS Code and opencode.

```bash
npx -y spacesheep@latest install
```

- It signs this machine in once. If it isn't signed in yet, it prints a
  `https://spacesheep.dev/cli?code=…` link: run it in the background, give the user
  the link, and wait for it to exit (the same as `spacesheep login` in "The CLI").
  With a login code from the message, pass it: `install --code ssc_…`.
- Each agent's config gets one entry that runs `spacesheep mcp`, a local stdio
  server on that one key, so **no agent asks for its own sign-in** and there is no
  `/mcp` → Authenticate step. An entry that already reached spacesheep is replaced,
  never doubled. It also installs the `/sheep` skill where each agent reads skills.
- It prints what it changed per agent; relay that list. A file it left alone (a
  config with comments) is named: configure that one agent by hand below.
- Then the restart in step 4 applies to every agent that was open, and step 3's
  check works through any of them.
- Several machines: from this one, `npx -y spacesheep@latest install --ssh
  host1,host2` (each gets its own key over ssh). `npx spacesheep mcp status` shows
  what's connected; `npx spacesheep mcp uninstall` undoes it.
- **If Claude Code blocks it in auto mode**, that's the same classifier note as the
  plugin below: tell the user what the command does and let them decide.
- With the Claude Code **plugin** installed, keep it: Claude Code gets the server by
  its URL, signed in by this machine's key, and (2.1.71+) skips the plugin's own
  copy of the same URL, so the plugin keeps `/sheep` and `/talk` with no doubled
  tools. Don't disable the plugin.
- `--ssh` leaves a machine's existing key alone and makes one only for a machine
  that has none; a machine without Node.js is named, and needs Node 20+ first.
  `--skip <agent or Claude home folder>` leaves one out (`--skip .claude-test`).

Use the per-client sections below when there's no shell on the user's machine, the
user wants only this one client, or `install` left a client alone.

### Claude Code

In a cloud session or a non-interactive run, skip this section: nothing here can
finish there. Use "Can nobody sign in from here?" above.

Shortest path — the plugin, which carries the `/sheep` skill and the MCP server
together and updates itself from spacesheep.dev:

```bash
claude plugin marketplace add https://spacesheep.dev/plugin/marketplace.json
claude plugin install spacesheep@spacesheep
```

> **Required after installation:** Restart your Claude session (exit and run claude again, or start a new terminal) for the MCP server and tools to take effect.

That's the whole setup; skip to step 3 (`claude plugin list` shows it
installed). **Plugin or `claude mcp add`, never both** — the plugin already
registers the server, so adding it again gives the user two copies of every
tool.

**If Claude Code blocks either command, that's expected — don't fight it.** In
auto mode, Claude Code's safety classifier stops an agent from installing a
plugin or adding an MCP server on a web page's say-so, and this is a web page.
The block is the classifier doing its job, so:

- don't retry;
- don't route around it — hand-editing `~/.claude.json` is the same action it
  just refused;
- tell the user what the command does and let them decide. It is this one line,
  which adds the spacesheep plugin marketplace and installs the plugin (the
  `/sheep` skill and the MCP server):

```
claude plugin marketplace add https://spacesheep.dev/plugin/marketplace.json && claude plugin install spacesheep@spacesheep
```

> **Required after installation:** Restart your Claude session (exit and run claude again, or start a new terminal) for the MCP server and tools to take effect.

Say it plainly ("Claude Code won't let me install a plugin on my own in auto
mode. This line installs the spacesheep plugin; run it yourself if you want it"),
and if they do, go on to step 4 for the restart and sign-in. If the marketplace
add went through before the block, the same line is still correct: adding it
twice is harmless.

If the user would rather have the MCP server alone, without the skill, use the
CLI instead (the same classifier note applies: if it's blocked, say what it does
and let them decide).
It writes the right file with the right shape, which hand-editing frequently
gets wrong:

```bash
claude mcp add --transport http --scope user spacesheep https://mcp.spacesheep.dev/mcp
```

> **Required after installation:** Restart your Claude session (exit and run claude again, or start a new terminal) for the MCP server and tools to take effect.

Pass `--scope` explicitly. It defaults to `local`, which pins the server to the
current directory only — usually not what "set this up for me" means. Use
`--scope user` for "available everywhere" (stored in `~/.claude.json`), and
`--scope project` only if it should be shared with everyone who clones this repo
(that writes `.mcp.json`, which is committed).

Confirm it registered before you do anything else:

```bash
claude mcp get spacesheep
```

The browser sign-in happens after the restart — see step 4. It's driven by the
`/mcp` command, which only the user can type; you can't run it for them.

To undo the whole thing: `claude mcp remove spacesheep --scope user`.

If you must write JSON by hand, the file is `~/.claude.json` for user scope
(top-level `mcpServers`) or `.mcp.json` in the project root for project scope.
It is **not** `~/.claude/settings.json` — that file does not read `mcpServers`,
and a config placed there is silently ignored.

```json
{
  "mcpServers": {
    "spacesheep": {
      "type": "http",
      "url": "https://mcp.spacesheep.dev/mcp"
    }
  }
}
```

`"type": "http"` is required. An entry with a `url` and no `type` is treated as a
stdio server and errors; `"type": "url"` is not a valid transport.

Only if OAuth is unavailable, add a header — using expansion, so the key stays
out of the file:

```json
"headers": { "Authorization": "Bearer ${SPACESHEEP_KEY}" }
```

Claude Code expands `${VAR}` and `${VAR:-default}` in `url`, `headers`, `env`,
`command`, and `args`.

The optional `/sheep` skill adds spacesheep's page-design conventions to Claude
Code. Offer it, don't assume it:

```bash
npx spacesheep-skill
```

### Cursor

The user can do it in one click instead of you editing a file: hand them
[Add to Cursor](https://cursor.com/en/install-mcp?name=spacesheep&config=eyJ1cmwiOiJodHRwczovL21jcC5zcGFjZXNoZWVwLmRldi9tY3AifQ%3D%3D),
which opens Cursor's install prompt with this entry filled in (the same link as
a deeplink: `cursor://anysphere.cursor-deeplink/mcp/install?name=spacesheep&config=eyJ1cmwiOiJodHRwczovL21jcC5zcGFjZXNoZWVwLmRldi9tY3AifQ%3D%3D`).
They confirm it, then sign in from Cursor's MCP settings.

To write it yourself: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json`
(project). Default to global unless the user wants it shared with the repo:

```json
{
  "mcpServers": {
    "spacesheep": {
      "url": "https://mcp.spacesheep.dev/mcp"
    }
  }
}
```

Cursor handles OAuth, so leave auth out entirely. If you do end up needing a key,
put it in the **global** file, never the project one — `.cursor/mcp.json` is
committed, and Cursor has no environment-variable expansion to hide a key behind.
If the user insists on the project file, add it to `.gitignore` first and say
plainly that the key will sit in plaintext on disk.

### Codex

On the user's own machine, prefer the CLI and OAuth. Check for an existing entry
with `codex mcp get spacesheep`; if it already points at the URL below, reuse it.
Otherwise, add the server:

```bash
codex mcp add spacesheep --url https://mcp.spacesheep.dev/mcp
```

This saves the server in Codex's user configuration (`$CODEX_HOME/config.toml`,
default `~/.codex/config.toml`) and starts OAuth automatically. Open the printed
authorization URL in the user's browser if it does not open itself. Keep the
command running while the user signs in and approves, then check that it reports
`Successfully logged in.` before claiming authentication succeeded. No API key
or shell-profile export is needed.

For an existing entry, or to retry an incomplete sign-in:

```bash
codex mcp login spacesheep
```

Verify the saved URL and enabled state:

```bash
codex mcp get spacesheep
```

Configuration, authentication, and tool availability are separate checks. If this
task does not have the tools yet, start a new Codex task; reload the client if
needed. Then run `list_spaces` to verify an authenticated tool call. This
connection is local to Codex on this machine; it does not add a ChatGPT connector.
ChatGPT needs the separate hosted-assistant setup above.

To undo: `codex mcp remove spacesheep`.

**Manual configuration or API-key fallback:** the OAuth configuration needs only:

```toml
[mcp_servers.spacesheep]
url = "https://mcp.spacesheep.dev/mcp"
```

Then run `codex mcp login spacesheep`. Only if OAuth cannot be used, add
`bearer_token_env_var = "SPACESHEEP_KEY"` to that section and have the user set the
variable in the environment that launches Codex. Never inline the key in TOML or
ask for it in chat. A GUI-launched Codex may not inherit exports from an
interactive-shell profile. When switching an existing API-key entry to OAuth,
remove its bearer-token setting or Authorization header before logging in;
preserve all other servers and settings.

On a remote or headless machine, do not send the user a loopback OAuth link:
its callback returns to the machine running Codex. Use the CLI sign-in or API-key
path described in this guide instead.

### Windsurf

`~/.codeium/windsurf/mcp_config.json`. The key here is `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "spacesheep": {
      "serverUrl": "https://mcp.spacesheep.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Windsurf's remote-MCP OAuth support is inconsistent across versions, so a key is
the reliable path here — unlike the other clients, where you should try OAuth
first. This file is cloud-synced for some users, so treat it as sensitive and
tell the user the key is stored in plaintext.

### Gemini CLI

An extension directory with two files — the manifest and the live skill as its
context file:

```bash
mkdir -p ~/.gemini/extensions/spacesheep && cd ~/.gemini/extensions/spacesheep
curl -fsSLO https://spacesheep.dev/plugin/gemini-extension.json
curl -fsSL https://spacesheep.dev/skill/sheep.md -o SHEEP.md
```

Gemini discovers the OAuth config from the server itself, so there's no key in
the manifest. `gemini extensions update spacesheep` isn't wired to this install
(it isn't a git source) — re-run the two curls to refresh.

### Antigravity (CLI and IDE)

Both read one shared file, `~/.gemini/config/mcp_config.json` (or
`.agents/mcp_config.json` in a project, for that workspace only). Read it first —
it holds the user's other servers — and add only the `spacesheep` entry:

```json
{
  "mcpServers": {
    "spacesheep": {
      "serverUrl": "https://mcp.spacesheep.dev/mcp"
    }
  }
}
```

The key is `serverUrl`. Antigravity ignores `url` and `httpUrl` for remote
servers, so an entry copied from the Claude Code or Cursor shape above loads as
nothing, silently. Leave auth out: spacesheep supports dynamic client
registration, which Antigravity uses to run the OAuth sign-in by itself.

To finish, the user opens the `/mcp` panel (a slash command they type, not you),
reloads if spacesheep isn't listed yet, and completes the browser sign-in; the
server shows **Authed** next to its name when it worked.

### Grok Build

Grok Build reads Claude Code's MCP config, so if `.mcp.json` or `~/.claude.json`
already has the `spacesheep` entry there is nothing to do. Otherwise:

```bash
grok mcp add --transport http spacesheep https://mcp.spacesheep.dev/mcp
```

### Hosted assistants (Claude.ai, ChatGPT, Grok, Gemini Spark)

Covered at the top of this guide — relay the steps to your user; there is no
config file to write. On Gemini, only Gemini Spark takes a custom MCP app;
regular Gemini chat can't connect one.

### Any other MCP client

Add it however that client adds a remote Streamable HTTP MCP server — OAuth if
offered, bearer token otherwise.

### The CLI — for CI, and for any agent with a shell

If the person wants to publish from a terminal, a script, or on every git push,
there is nothing to configure in this client. The open-source `spacesheep` CLI
(<https://github.com/micmmakarov/spacesheep-cli>, MIT) is a plain client of the
same MCP server:

```bash
npx spacesheep login          # browser sign-in once; key stored locally
npx spacesheep deploy ./dist  # a folder with index.html, or one .html file
```

This is also the way **you** publish when the MCP server isn't connected yet, or
isn't authorized: it is the same server over a different transport, so it works
inside a session that is already running, with no restart and no `/mcp`. Reach
for it instead of telling someone their page has to wait — `spacesheep login`
prints a code and a `spacesheep.dev/cli?code=…` link you can hand them, and the
key it stores is this machine's, independent of any MCP grant.

**Run the login yourself; the person's only step is the Approve click.** It asks
nothing in the terminal (no prompt, no password), so don't hand it to them as a
`!` command to type. It prints the code and the link, opens a browser where it
can, and exits as soon as they approve on any device, their phone included.
Because it waits up to 10 minutes, start it as a background task, give them the
link in one line, and publish when it exits (or when `spacesheep whoami`
answers). Don't make them come back to tell you they approved: the login exiting
is the signal. A shell `&` tells you nothing when it ends, so if that is all you
have, poll `whoami`.

**If Claude Code's auto mode blocks `npx -y spacesheep@latest`, ask; don't work
around it.** Its classifier sees the person's words and your command, never the
page that told you to run it, so a package from npm reads as code nobody asked
for. Don't retry on your own, and don't swap in another way to run it. Tell them
in one line what it does ("Auto mode won't run spacesheep's open-source CLI from
npm on my own; reply *yes, run it* and I'll publish the page") and, once they
have, run the same command once. Their words are what it reads. Write the page
before you ask, so nothing waits on the answer but the publish.

On a machine that cannot open a browser (a lab box, a server, a shared
workstation), they create a key at
<https://spacesheep.dev/settings/api-keys#create> and paste the one line the
page shows on each machine:

```bash
npx -y spacesheep@latest connect ss_…             # key named after the hostname
npx -y spacesheep@latest connect ss_… bench-03     # or a name they choose
```

Each machine ends up with its own key (the pasted key never lands on disk),
listed by name in Settings and revocable on its own. Needs Node 20+.

For GitHub Actions, they add an API key from
<https://spacesheep.dev/settings/api-keys#create> as the repo secret `SPACESHEEP_KEY`:

```yaml
- uses: actions/checkout@v4
- uses: micmmakarov/spacesheep-cli@v1
  with:
    dir: dist
    key: ${{ secrets.SPACESHEEP_KEY }}
```

The first run creates the space and writes `.spacesheep.json` next to the files;
commit it so later runs update the same space.

Anywhere else — a server, a container, a headless agent run — set
`SPACESHEEP_KEY` in the environment and every command uses it; nothing is stored.

What `deploy` tells you back: `design_review` and `screenshot` are MCP tools, so a
CLI publish can't run them — open the URL to check it. A warning that the page
"was auto-anchored" (no `data-ss-id`) is only about comments on documents; for a
game, an app or a one-off demo page it's safe to ignore.

## Step 3 — verify what you can, before restarting

The restart ends your session, so check everything checkable now.

**Config shape** — whichever client you configured, re-read the file you wrote
and confirm it parses and contains the entry you intended. On Claude Code,
`claude mcp get spacesheep` does this for you; on Codex, use
`codex mcp get spacesheep`.

**The key, if you set one up.** Check the variable actually exists in the
environment first — an unset variable and a bad key both come back `401`, so
without this you can't tell them apart:

```bash
[ -n "${SPACESHEEP_KEY:-}" ] && echo "var is set" || echo "VAR IS NOT SET"
curl -s -w '\n%{http_code}\n' \
  -H "Authorization: Bearer $SPACESHEEP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://mcp.spacesheep.dev/mcp
```

`401` means the key or the variable is wrong — fix it before the restart. Read
the body, not just the status: a `200` carrying a JSON-RPC `error` object is also
a failure.

Note that the variable has to be visible to the *client's* process, not just your
shell. A client launched from a GUI or IDE doesn't inherit an `export` from an
interactive shell profile — that applies to Claude Code's `${VAR}` expansion just
as much as to Codex's `bearer_token_env_var`.

## Step 4 — hand off across the restart

New MCP configurations may need a fresh session to load. On Codex, start a new
task and reload the client if needed; on other clients, restart or reload.
**Publishing does not have to wait for it** — if there is a page to ship now, ship
it with the CLI above and let the restart be a separate errand. Before they restart, tell them in one message:

1. the file you changed, and how to undo it;
2. that they need a new task on Codex, or a restart on other clients, and then
   — on Claude Code — type `/mcp` themselves
   and pick **Authenticate** to do the browser approval (a slash command is user
   input; an agent can't send it). On a **brand-new account** they'll also claim
   an `@username`, which becomes their URL namespace, so pages publish to
   `spacesheep.dev/@them/<title>`. Don't say this to someone who already has an
   account — signing in again doesn't ask, and telling a returning user to pick a
   username they already picked reads as a broken integration;
3. that afterwards they should ask their agent to **run `list_spaces`** to
   confirm the connection.

An empty list is a pass — it means an authenticated call succeeded on a new
account.

Three ways it goes wrong, and what each one means:

- **The tools aren't there at all** — the client never read the config. Re-check
  the path for that client, confirm the file parses, and confirm the restart
  actually happened. On Claude Code, also check `--scope`: a `local`-scope server
  only exists in the directory it was added from.
- **The server is listed but no browser prompt ever appears, and calls report
  that auth is required** — automatic OAuth discovery didn't kick in. Have the
  user run `/mcp` and choose Authenticate explicitly on Claude Code, or run
  `codex mcp login spacesheep` on Codex. If that still does nothing,
  fall back to an API key.
- **The tools are there but every call is an auth error** — the grant didn't
  complete or the key is wrong. Redo the browser approval, or re-check the key
  with the step 3 curl.

## Step 5 — offer a first page

Then offer to publish something, since that's the fastest way to see what was
just connected:

```
Deploy a quarterly metrics report from this data to spacesheep
Build an architecture overview of this repo and publish it
```

`deploy` builds one self-contained HTML file — no CDN, no build step — and
returns a private URL. Tool arguments and the access model are documented at
<https://spacesheep.dev/docs>.

Live data and live video go into a page the same way: a stream from a server
(<https://spacesheep.dev/streams>), or a camera, a phone or a screen
(<https://spacesheep.dev/docs/streams#video>: publish a page with
`<video data-ss-stream="lab/cam-1">`, then open
`https://spacesheep.dev/film/lab/cam-1` on the phone).

## Settings you can change from here

Most of the Settings page is one MCP call — keys, the AI model, config groups,
teams. Which call does what, what needs the person in a browser, and what isn't
on MCP yet is one page. Read it before sending your user to Settings:

- the document itself, readable by any fetcher:
  <https://0edcbb7c-c285-450d-8043-cdc3401243da.spacesheep.app/>
- the same page for people: <https://spacesheep.dev/@misha/set-up-spacesheep>
- once you're connected: `read_space` with either link.

## Beyond this client — Telegram and Slack

Your user may ask for spacesheep in a chat app next. Those are not MCP clients
and there is nothing for you to configure; each is a link the person taps.
Relay the steps, then stop:

- **Telegram:** open a DM with **@TheSpaceSheepBot**, send `/start`, tap the
  link it replies with. (Or copy a one-time code from Settings → Telegram at
  <https://spacesheep.dev/settings/telegram> and send `/start <code>`.) In a
  group, add the bot and send `/bind` to tie the group to an account or org.
- **Slack:** an org owner connects the workspace from the org's Settings page,
  `https://<org>.spacesheep.dev/settings`.

The full list, with what each channel can do, is at
<https://spacesheep.dev/docs/telegram>.

## Something here wrong or broken?

Report it from where you are — no browser needed. With the MCP tools, call
`submit_feedback` (a message and a fresh `client_id`). From a shell:

```bash
npx -y spacesheep@latest feedback "setup.md step 2 failed: …" --client-id setup-report-001 --category bug
```

Either lands in the account's thread at <https://spacesheep.dev/feedback>, where
the team replies. Leave keys and other secrets out of the message.