# sf setup agent

Configure MCP and install the Spacefast skill for every agent on your machine with one CLI command

After this page you can point every agent client on your machine at Spacefast with one command, know exactly which files it touches, and drive it non-interactively in a script.

## The command

```
sf setup agent
```

It detects the agent clients you have installed, writes each one’s MCP config, and installs the Spacefast skill. It is idempotent, so running it again is safe.

Run it without arguments and it asks two questions. First a checkbox list of the clients it found. Then how MCP should connect.

| Choice | What it writes |
| --- | --- |
| Remote (default) | `sf mcp proxy` over stdio, using your CLI login |
| Local | `sf mcp`, a checkout-aware stdio server |
| Remote (OAuth) | The hosted URL directly, and your editor handles OAuth |
| Skip | Nothing. Skills only |

Then ask your agent for something read-only to confirm the config landed.

Use the Spacefast MCP server to search the docs for version rollback.

## Non-interactive

```
sf setup agent -y
```

`--yes` skips both prompts, auto-detects your clients, and configures **remote proxy** MCP. That is the same default the interactive picker offers.

## Flags

| Flag | What it does |
| --- | --- |
| `--agent <id>` | Configure one client. Repeat for more. `auto` detects, `all` covers everything, `generic` writes a project `.mcp.json` |
| `--yes`, `-y` | Skip prompts and auto-detect |
| `--project`, `-p` | Install skills into this project instead of the client’s global skills directory |
| `--remote` | Hosted MCP through `sf mcp proxy` and your CLI login |
| `--local` | Local stdio MCP instead of the proxy. Cannot be combined with `--remote` or `--oauth` |
| `--oauth` | With `--remote`, connect to the hosted URL directly and let the editor handle OAuth. Requires `--remote` |
| `--skip-mcp` | Install skills without configuring MCP |
| `--force` | Overwrite locally modified or unverified Spacefast skill files |
| `--handoff` | Redeem a one-use handoff link from the dashboard before generating setup. The link is read from stdin |

```
sf setup agent -y --agent cursor --remote --oauth
```

## What it writes into your project

Skills are the only thing that lands in your project, and only with `--project`. Everything else goes to the client’s global config, with two exceptions. VS Code’s MCP config is project-scoped at `<project>/.vscode/mcp.json`, and `--agent generic` writes `<project>/.mcp.json`.

With `--project`, the skill goes into that client’s project skills directory. For most clients that is `<project>/.agents/skills/spacefast/`.

Config merges are careful. Only the client’s own root key is rewritten, and every other top-level key in the file passes through untouched. JSONC input parses, but comments are not preserved on write. A symlinked or non-file config is refused rather than followed, with `Refusing symbolic link or non-file MCP config`.

If `--agent auto` detects nothing, it falls back to the universal `.agents` target and writes no MCP config at all.

## Related commands

### `sf mcp install`

MCP config only, with no skill install.

```
sf mcp install --agent claude-code
sf mcp install --agent cursor --remote --oauth
```

Same method resolution. `--oauth` gives the direct hosted URL, `--local` gives `sf mcp`, and anything else gives the proxy.

### `sf agents init`

Writes a Spacefast block into `AGENTS.md` in the current directory, wrapped in `<!-- SPACEFAST START -->` and `<!-- SPACEFAST END -->` markers. Running it again replaces the block in place and leaves the rest of the file alone. Broken or duplicated markers make it stop rather than guess.

```
sf agents init
```

### `sf plugins`

Runs the universal plugin installer against a pinned version.

```
sf plugins --agent claude-code
sf plugins --agent codex --dry-run
```

`--agent` defaults to `claude-code`. `--dry-run` prints the installer command without running it. Clients with no installer target are refused with a message pointing you back at `sf setup agent`.