l4 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.
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.
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 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 clients at. 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.
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:
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 mcp add --scope user | Remote HTTP |
| Claude Desktop | claude_desktop_config.json | Local stdio, running l4 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.
install configures Claude Code by running Claude Code's own CLI, because that configuration file also holds per-project state the vendor tool owns.
Where the credential goes
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, which reads your keychain.
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:
l4 mcp install --client cursor --token $ORG_A_KEY
l4 mcp install --client cursor --name levelfour-org-b --token $ORG_B_KEYA read-write key alongside the default read-only one, which the tools that record a decision need (Key scopes):
l4 mcp install --client cursor --name levelfour-rw --token $READ_WRITE_KEYA second entry pointed somewhere other than production:
l4 mcp install --client cursor --name levelfour-staging --endpoint https://mcp.example.internal/mcpExamples
Configure everything it can confirm:
l4 mcp installOne client:
l4 mcp install --client cursorSeveral at once, without writing the key to disk:
l4 mcp install --client cursor --client vscode --client windsurf --key-source envMachine-readable, for a provisioning script:
l4 mcp install --client cursor --jsonl4 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: what is wired up, and what is notl4 mcp uninstall: remove the entry, and the backups holding the old keyl4 mcp serve: the local server this points Claude Desktop at- Connecting a client: the configuration each client expects, by hand