# l4 mcp install

> Add the LevelFour MCP server to the agent clients on this machine, without hand-editing JSON.

Source: https://docs.levelfour.ai/cli/commands/mcp/install


`l4 mcp install` writes the LevelFour MCP server into the configuration of the agent clients it finds on this machine, using a LevelFour API key.

```bash
l4 mcp install [flags]
```

With no `--client`, it configures every client it can confirm. With no `--token`, it uses the credential `l4` already holds, and opens the browser to mint a `read` key when there is none.

> **Note**
>
> Restart the client after an install, or it will not pick up the new entry.

A key is one of two ways in. A client pointed at `https://mcp.levelfour.ai/mcp` with no header sends you to the browser to sign in instead. Reach for `install` when you want one command to configure every client on the machine, or when the client runs unattended. [Connecting a client](/mcp/authentication) compares them.

## Flags

| Flag           | Description                                                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--client`     | Client to configure: `claude-code`, `claude-desktop`, `cursor`, `vscode`, `windsurf`. Repeatable. Defaults to every client detected      |
| `--name`       | Name for the server entry. Defaults to `levelfour`                                                                                       |
| `--endpoint`   | MCP endpoint to point every client at, Claude Desktop included. Defaults to the hosted server                                            |
| `--key-source` | `inline` (default) writes the credential into the config. `env` writes a reference to the `LEVELFOUR_TOKEN` environment variable instead |

Global flags (`--json`, `--jq`, `--template`, `--quiet`, `--token`, `--api`) apply. See [CLI overview](/cli#global-flags).

## Which clients it touches

The command distinguishes proof that a client is installed from a hint of it. An executable on `PATH`, an application bundle, or an existing MCP configuration file counts as proof. A directory the client created once is only a hint, because those outlive an uninstall, and writing a credential into a fresh configuration for software that is no longer there leaks it.

It names the clients it only has a hint of, and skips them:

```text
Detected Claude Code, Cursor. Configuring all of them; use --client to narrow.
Skipping VS Code: configuration was found but the application was not. Add --client to configure it anyway.
```

## What it writes

Each vendor expects the same facts in a different file under a different key, so the shape differs per client.

| Client         | Written to                            | Transport                                                      |
| -------------- | ------------------------------------- | -------------------------------------------------------------- |
| Claude Code    | `~/.claude.json`                      | Remote HTTP                                                    |
| Claude Desktop | `claude_desktop_config.json`          | Local stdio, running [`l4 mcp serve`](/cli/commands/mcp/serve) |
| Cursor         | `~/.cursor/mcp.json`                  | Remote HTTP                                                    |
| VS Code        | user-profile `mcp.json`               | Remote HTTP                                                    |
| Windsurf       | `~/.codeium/windsurf/mcp_config.json` | Remote HTTP                                                    |

`install` parses the existing configuration and merges into it. It touches only the entry under `--name`, leaves the rest of the file as it was, and takes a dated `.l4-backup-<timestamp>` copy first. A file that is not valid JSON stops the install for that client; `install` never overwrites it.

`~/.claude.json` also holds Claude Code's per-project state. `install` keeps every other key in it and replaces the file in one step rather than rewriting it in place, so the server loads in every project and nothing else changes.

## Where the credential goes

> **Warning**
>
> By default `install` writes the key into the client's configuration file in plain text.

The CLI writes files it creates itself `0600` on macOS and Linux.

`--key-source env` writes a reference instead, so no key lands on disk. The spelling differs per vendor:

| Client                | Reference written                                             |
| --------------------- | ------------------------------------------------------------- |
| Claude Code, Windsurf | `${LEVELFOUR_TOKEN}`                                          |
| Cursor                | `${env:LEVELFOUR_TOKEN}`                                      |
| VS Code               | an `inputs` prompt, stored in the editor's own secret storage |

Export `LEVELFOUR_TOKEN` in the environment the client starts from, except for VS Code, which prompts once and keeps the value itself. `LEVELFOUR_TOKEN` is the variable `l4` itself reads, so one export serves the CLI and every client.

Claude Desktop never receives a key either way. It runs [`l4 mcp serve`](/cli/commands/mcp/serve), which reads your keychain and relays the hosted server.

## More than one entry

An API key belongs to exactly one organization, and to one scope. `--name` is how you keep several entries side by side, because each install only touches the entry under that name.

Two organizations, one client:

```bash
l4 mcp install --client cursor --token $ORG_A_KEY
l4 mcp install --client cursor --name levelfour-org-b --token $ORG_B_KEY
```

A read-write key alongside the default read-only one, which the tools that record a decision need ([Key scopes](/authentication#key-scopes)):

```bash
l4 mcp install --client cursor --name levelfour-rw --token $READ_WRITE_KEY
```

A second entry pointed somewhere other than production:

```bash
l4 mcp install --client cursor --name levelfour-staging --endpoint https://mcp.example.internal/mcp
```

## Examples

Configure everything it can confirm:

```bash
l4 mcp install
```

One client:

```bash
l4 mcp install --client cursor
```

Several at once, without writing the key to disk:

```bash
l4 mcp install --client cursor --client vscode --client windsurf --key-source env
```

Machine-readable, for a provisioning script:

```bash
l4 mcp install --client cursor --json
```

> **Success**
>
> [`l4 mcp status`](/cli/commands/mcp/status) reads the entries back. **Configured** turns to `yes`, and the **Endpoint** column shows what that entry now points at. That is the proof, not the absence of an error message.

## Errors

| Exit | Symptom                                   | Cause                                                                     |
| ---- | ----------------------------------------- | ------------------------------------------------------------------------- |
| `1`  | `no MCP client detected on this machine`  | Nothing confirmed. Install a client, or name one with `--client`          |
| `1`  | `no client was configured`                | Every client attempted failed. The message names each failure             |
| `1`  | `N of M clients failed`                   | Some succeeded, some did not. The successful ones are configured          |
| `1`  | `unknown client`                          | `--client` was given a name outside the supported set                     |
| `1`  | `is not valid JSON, so it was left alone` | The client's configuration file is malformed. Fix or move it, then re-run |

A partial failure exits non-zero in both human and `--json` mode, because a client that failed has no LevelFour tools.

## Related

* [`l4 mcp status`](/cli/commands/mcp/status): what is wired up, and what is not
* [`l4 mcp uninstall`](/cli/commands/mcp/uninstall): remove the entry, and the backups holding the old key
* [`l4 mcp serve`](/cli/commands/mcp/serve): the local server this points Claude Desktop at
* [Connecting a client](/mcp/authentication): the configuration each client expects, by hand