# Claude Code, Cursor and other agents

> How Excellent attaches to the agent you already use: the file and the exact MCP entry the installer writes for each of the 28 agents it supports, and how to undo it.

Excellent does not replace your agent and does not ship a model. It attaches to
the agent you already run, as an MCP server, and checks what that agent produces.

## What the installer does to your machine

> **If you installed 0.1.0 from npm.** `@excellent-so/cli` 0.1.0, the release npm
> serves (checked October 23, 2026), predates `install-agent-mcps`. The installer
> skips this step and says so, and no agent config is changed. You can register that
> release's server by hand: find your agent in [the table below](https://www.excellent.so/docs/claude-code-and-cursor#every-agent-and-its-file)
> and follow [Adding the entry by hand](https://www.excellent.so/docs/claude-code-and-cursor#adding-the-entry-by-hand). That release does not
> have the verification tools this page lists: with no profile set it advertises 234
> tools, and none of the fourteen named under Claude Code is among them. The rest of
> this page describes the next CLI release.

When you install Excellent, it runs `install-agent-mcps`. That command finds **every**
agent on your machine that it knows how to configure, and writes an `excellent` server
entry into each one's own config file. Not just the agent you were using at the time.
If it finds none, each `excellent` command you run checks again until one setup succeeds.

Worth knowing before you run it: it knows 28 agents, so it may touch up to 27 vendor
config files, plus OpenClaw's own registry through OpenClaw's command line. It adds one
`excellent` entry and leaves the rest of each file's content alone. Every write goes to
a temporary file that is then renamed into place. It refuses a config it cannot parse,
and a TOML or YAML config whose `excellent` entry is ambiguous. JSON files are written
back with two-space indentation; OpenCode and Kilo Code keep the comments in their JSONC.
You can run it again safely: once an entry matches this install, it is left as it is.

To do it yourself later, or after installing through npm:

```bash
excellent install-agent-mcps
```

It prints one line for each agent it configured, naming the file it wrote, and asks you
to restart those agents. Agents it cannot configure get no line; they are listed
[below](https://www.excellent.so/docs/claude-code-and-cursor#agents-it-detects-but-does-not-configure). Add `--json` for the full report.

## Every agent and its file

Names are as the installer prints them. Paths are for macOS, the one platform Excellent
supports today.

| Agent | File it writes | Entry |
|---|---|---|
| Amazon Q Developer CLI | `~/.aws/amazonq/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Amp | `~/.config/amp/settings.json` | [`amp.mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#amp) |
| Antigravity CLI | `~/.gemini/config/mcp_config.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Auggie CLI | `~/.augment/settings.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Claude Code | `~/.claude.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Cline CLI | `~/.cline/data/settings/cline_mcp_settings.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Codebuff | `~/.agents/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Codex | `~/.codex/config.toml` | [`[mcp_servers.excellent]`](https://www.excellent.so/docs/claude-code-and-cursor#toml-codex-grok-build-and-open-interpreter) |
| Crush | `~/.config/crush/crush.json` | [`mcp`](https://www.excellent.so/docs/claude-code-and-cursor#crush) |
| Cursor Agent | `~/.cursor/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Devin CLI | `~/.config/devin/mcp_config.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Factory Droid | `~/.factory/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Gemini CLI | `~/.gemini/settings.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| GitLab Duo CLI | `~/.gitlab/duo/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| goose | `~/.config/goose/config.yaml` | [`extensions`](https://www.excellent.so/docs/claude-code-and-cursor#goose) |
| Grok Build | `~/.grok/config.toml` | [`[mcp_servers.excellent]`](https://www.excellent.so/docs/claude-code-and-cursor#toml-codex-grok-build-and-open-interpreter) |
| Hermes Agent | `~/.hermes/config.yaml` | [`mcp_servers`](https://www.excellent.so/docs/claude-code-and-cursor#hermes-agent) |
| Junie CLI | `~/.junie/mcp/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Kilo Code CLI | `~/.config/kilo/kilo.json` | [`mcp`, a `local` server](https://www.excellent.so/docs/claude-code-and-cursor#opencode-and-kilo-code-cli) |
| Kimi Code CLI | `~/.kimi-code/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Kiro CLI | `~/.kiro/settings/mcp.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Open Interpreter | `~/.openinterpreter/config.toml` | [`[mcp_servers.excellent]`](https://www.excellent.so/docs/claude-code-and-cursor#toml-codex-grok-build-and-open-interpreter) |
| OpenClaw | OpenClaw's own registry, through `openclaw mcp` | [`openclaw mcp set`](https://www.excellent.so/docs/claude-code-and-cursor#openclaw) |
| OpenCode | `~/.config/opencode/opencode.json` | [`mcp`, a `local` server](https://www.excellent.so/docs/claude-code-and-cursor#opencode-and-kilo-code-cli) |
| Qwen Code | `~/.qwen/settings.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |
| Rovo Dev CLI | `~/.rovodev/mcp_config.json` | [`mcpServers`, with `transport`](https://www.excellent.so/docs/claude-code-and-cursor#rovo-dev-cli) |
| Windsurf Cascade | `~/.codeium/windsurf/mcp_config.json` | [`mcpServers`](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry) |

Some agents move their config with an environment variable, and Excellent follows it:
`GROK_HOME` (Grok Build), `HERMES_HOME` (Hermes Agent), `COPILOT_HOME` (GitHub Copilot
CLI), `KIMI_CODE_HOME` (Kimi Code CLI), `CLINE_DATA_DIR` (Cline CLI), `ROVODEV_HOME`
(Rovo Dev CLI), `OPENCODE_CONFIG` (OpenCode), `GLAB_CONFIG_DIR` (GitLab Duo CLI), and
`OPENCLAW_CONFIG_PATH` or `OPENCLAW_STATE_DIR` (OpenClaw). `XDG_CONFIG_HOME` moves every
`~/.config` path above, and GitLab Duo CLI's file to `$XDG_CONFIG_HOME/gitlab/duo/mcp.json`.
OpenCode uses `opencode.jsonc` when that is the only one of the two files that exists.
Rovo Dev CLI uses the `mcpConfigPath` set in `~/.rovodev/config.yml`, and otherwise
falls back to an existing legacy `mcp.json`.

### Agents it detects but does not configure

Excellent recognizes these agents but writes no config for them:

| Agent | Why not |
|---|---|
| Zed Agent | Zed's documented MCP server settings do not establish which working directory the server runs in, so Excellent will not create an entry it cannot verify as portable. |
| Mistral Vibe | The same: its MCP schema does not establish the working directory. |
| OpenHands CLI | The same: there is no reviewed way to persist the server's working directory. |
| Aider | It has no native MCP client. |
| Continue CLI | It takes MCP servers from its own platform config, not a local file. |
| Grok Bot | It is a desktop control surface. The work runs on Grok Bot's cloud computer. |
| Jules Tools | The work runs in a cloud VM, not on your machine. |
| mini-SWE-agent | No native MCP client is documented. |
| Pi Agent | It ships no native MCP client, on purpose. |
| Plandex | No persistent MCP config is documented. |
| Roo Code CLI | Its MCP settings are per editor profile or per project, so there is no single file to write. |
| Sourcegraph Cody CLI | No persistent MCP config is documented. |
| SWE-agent | It uses its own tool bundles rather than a persistent MCP config. |
| Trae Agent | Its MCP map lives in a project YAML you choose, so there is no single file to write. |
| Warp Oz | It takes MCP servers per run (`--mcp`) or from Warp's cloud, with no local file. |

## The entry it writes

Two paths appear in every entry. `/absolute/path/to/node` is the Node.js that ran the
installer; `node -p process.execPath` prints it. `/absolute/path/to/@excellent-so/cli/dist`
is the installed package's `dist` folder, which holds `server.js`;
`echo "$(npm root -g)/@excellent-so/cli/dist"` prints it. An npm or `curl | sh` install
writes no environment variables.

### The standard `mcpServers` entry

Claude Code, Cursor Agent, Gemini CLI, GitHub Copilot CLI, Windsurf Cascade, Amazon Q
Developer CLI, Antigravity CLI, Auggie CLI, Cline CLI, Codebuff, Devin CLI, Factory
Droid, GitLab Duo CLI, Junie CLI, Kimi Code CLI, Kiro CLI and Qwen Code all get the same
stdio block:

```json
{
  "mcpServers": {
    "excellent": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
      "cwd": "/absolute/path/to/@excellent-so/cli/dist",
      "env": {}
    }
  }
}
```

### Other JSON entries

#### Rovo Dev CLI

The same block, but Rovo Dev names stdio with `transport` instead of `type`:

```json
{
  "mcpServers": {
    "excellent": {
      "transport": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
      "cwd": "/absolute/path/to/@excellent-so/cli/dist",
      "env": {}
    }
  }
}
```

#### Amp

Amp's map is one key with a dot in its name, `amp.mcpServers`, and the entry has no `type`:

```json
{
  "amp.mcpServers": {
    "excellent": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
      "cwd": "/absolute/path/to/@excellent-so/cli/dist",
      "env": {}
    }
  }
}
```

#### Crush

Crush keeps its servers under `mcp`:

```json
{
  "mcp": {
    "excellent": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
      "cwd": "/absolute/path/to/@excellent-so/cli/dist",
      "env": {}
    }
  }
}
```

#### OpenCode and Kilo Code CLI

A `local` server, with Node and the server script together in one `command` array:

```json
{
  "mcp": {
    "excellent": {
      "type": "local",
      "command": [
        "/absolute/path/to/node",
        "/absolute/path/to/@excellent-so/cli/dist/server.js"
      ],
      "cwd": "/absolute/path/to/@excellent-so/cli/dist",
      "environment": {},
      "enabled": true
    }
  }
}
```

If the file already nests its servers under `mcp.servers` (OpenCode v2), the entry goes
there, with `"disabled": false` in place of `"enabled": true`.

### TOML: Codex, Grok Build and Open Interpreter

```toml
[mcp_servers.excellent]
command = "/absolute/path/to/node"
args = [ "/absolute/path/to/@excellent-so/cli/dist/server.js" ]
cwd = "/absolute/path/to/@excellent-so/cli/dist"
env = {}
```

### YAML entries

#### Hermes Agent

```yaml
mcp_servers:
  excellent:
    command: "/absolute/path/to/node"
    cwd: "/absolute/path/to/@excellent-so/cli/dist"
    args:
      - "/absolute/path/to/@excellent-so/cli/dist/server.js"
    env: {}
```

#### goose

goose gets a stdio extension:

```yaml
extensions:
  excellent:
    type: "stdio"
    name: "Excellent"
    enabled: true
    cmd: "/absolute/path/to/node"
    cwd: "/absolute/path/to/@excellent-so/cli/dist"
    args:
      - "/absolute/path/to/@excellent-so/cli/dist/server.js"
    env_keys: []
    envs: {}
    timeout: 300
```

### OpenClaw

OpenClaw owns its config file, so Excellent does not edit it. It registers through
OpenClaw's own command instead:

```bash
openclaw mcp set excellent '{"command":"/absolute/path/to/node","args":["/absolute/path/to/@excellent-so/cli/dist/server.js"],"cwd":"/absolute/path/to/@excellent-so/cli/dist","env":{},"transport":"stdio"}'
```

The only environment keys Excellent will ever own or overwrite in an entry are
`EXCELLENT_*`, `INTEGRATIONS_CRON_SECRET` and `ELECTRON_RUN_AS_NODE`. In the JSON entries,
anything else you put in `env` is preserved when Excellent rewrites the entry. When it
rewrites a TOML, YAML or OpenClaw entry it writes only its own keys, so keep your own
variables out of those.

Restart or reload the agent after installing, or it will not see the new server.

## Adding the entry by hand

With 0.1.0, or if you would rather not let the installer write agent configs:

1. Find your agent in [the table above](https://www.excellent.so/docs/claude-code-and-cursor#every-agent-and-its-file) and open its file.
   Create it if it does not exist.
2. Add the entry for its shape from [The entry it writes](https://www.excellent.so/docs/claude-code-and-cursor#the-entry-it-writes) inside the
   map that is already there, next to any other servers. Do not replace the file. For
   OpenClaw, run the `openclaw mcp set` command instead.
3. Replace the two placeholder paths with the output of `node -p process.execPath` and
   `echo "$(npm root -g)/@excellent-so/cli/dist"`.
4. Restart the agent.

Excellent does not write an entry for Zed, Mistral Vibe or OpenHands, and does not offer
one to copy, for the reason in [the table above](https://www.excellent.so/docs/claude-code-and-cursor#agents-it-detects-but-does-not-configure).

## Claude Code

After a restart, Claude Code lists the Excellent tools under the `excellent` server.
By default it sees **14 tools**, not the full registry. The default profile is
`product`, which is the verification journey and nothing else:

- `verification_v2_commands`, `verification_v2_dispatch`
- `universal_verification_status`, `universal_verification_open_attempt`,
  `universal_verification_submit_attempt`, `universal_verification_propose_amendment`,
  `universal_verification_request_review`, `universal_verification_trust_root`
- `session_create`, `session_attach`, `session_event`, `session_evidence_record`,
  `session_trajectory`, `session_claim`

Set `EXCELLENT_MCP_PROFILE=core` or `full` in the server's `env` block for a wider
belt. Treat the profile as a menu rather than a fence: the enforced boundary is
`EXCELLENT_MCP_ALLOW`, which is checked at dispatch. Both are `EXCELLENT_*` keys, which
Excellent owns, so the next `install-agent-mcps` finds an entry that differs from the one
it would write and writes it back without them. Set them again after a re-run.

In use, you do not call these yourself. The agent opens an attempt against a Work item,
submits its output, and reads the status back. Excellent records the attempt and,
separately, a verifier reaches a verdict, which the agent cannot issue for itself. See
[How verification decides](https://www.excellent.so/docs/how-verification-decides).

### Hooks and skills

> **Only in a monorepo checkout.** If you installed with `curl | sh` or
> `npm i -g @excellent-so/cli`, you get MCP registration and nothing else. No hooks,
> no skills. The hook and skill wiring needs an Excellent monorepo root and is skipped
> without one.

Inside a checkout, `excellent-mcp install-skills` additionally writes three Claude Code
hooks into `<repo>/.claude/settings.json`: `SessionStart`, `Stop`, and `PreToolUse`
matching `Bash`. There is no `PostToolUse` hook. It only adds missing entries; your own
hooks are left alone, and an unparseable settings file is refused rather than rewritten.

What they do: the session hook reaps MCP server processes whose host died. The stop
hook reminds you if you still hold in-progress work. The Bash hook is the interesting
one: it blocks a `git commit` or `git push` when the agent holds no claim, and blocks
bulk staging (`git add -A`, `git commit -a`) in a shared working tree.

It also symlinks the shipped skill packs into `~/.claude/skills/`. That mirror is for
Claude Code's UI only; the `skill_list` and `skill_get` tools read the repo directly and
do not need it.

## Cursor

Cursor gets **MCP and only MCP**: an `excellent` entry in `~/.cursor/mcp.json`, in
[the standard shape](https://www.excellent.so/docs/claude-code-and-cursor#the-standard-mcpservers-entry). The installer calls it Cursor
Agent. Excellent writes no `.cursorrules`, no `.cursor/rules/*.mdc`, no hooks and no
project-scoped config.

Cursor is detected from the `cursor-agent` binary or from Cursor.app being installed.
The bare `agent` alias is deliberately not accepted as evidence, since it belongs to
too many things.

Separately, Cursor can be a backend for Excellent's own REPL:

```bash
excellent chat --cli cursor
```

That routes each turn through your local `cursor-agent` using its auth, with no API key.
`claude` is the first-class backend there. It gets the full belt and resumable
sessions; the others run headless.

## Repository context

`excellent init` writes `AGENTS.md` and `.excellent/context.md` into the repository.
The Excellent chat reads `AGENTS.md`, `CLAUDE.md` and `.excellent/context.md` per
directory. Claude Code reads `CLAUDE.md` and `AGENTS.md` on its own. Keeping the
repository facts in those files means both tools see the same thing.

## Undoing it

To disconnect one agent, delete the `excellent` entry from its file in
[the table above](https://www.excellent.so/docs/claude-code-and-cursor#every-agent-and-its-file), then restart the agent. For OpenClaw, run:

```bash
openclaw mcp unset excellent
```

Excellent does not put a removed entry back by itself. After the first setup that
succeeds, it records that in `~/.excellent/agent-mcp-first-use-v1.json`, and from then on
it writes agent configs only when you ask it to, as with `install-agent-mcps`.

In a source checkout, `excellent-mcp uninstall-skills` removes Excellent's own symlinks
and the exact `excellent` entries it added. It never deletes a real directory and never
touches another vendor's entries. In an npm or `curl | sh` install it does not recognize
the installer's entries as its own and leaves them in place, so remove them by hand as
above.

## Related

- [MCP](https://www.excellent.so/docs/integrate/mcp): connecting anything else that speaks MCP.
- [Quickstart](https://www.excellent.so/docs/quickstart): the whole path, end to end.
- [CLI reference](https://www.excellent.so/docs/cli): every command and environment variable.

Source: https://www.excellent.so/docs/claude-code-and-cursor
