IDE Setup

Steroid connects to four coding agents — Cursor, Claude Code, OpenAI Codex and the GitHub Copilot CLI. Setup registers Steroid as an MCP server so each agent launches its own steroid mcp-server process over stdio, adds a short instructions block, and installs Steroid's agent skills. No credentials are written into any agent's configuration.

Supported Agents

Agent	Setup target	Needs	MCP entry written to
Cursor	`cursor`	Cursor app and the `agent` CLI on PATH	`~/.cursor/mcp.json` (all platforms)
Claude Code	`claude-code`	`claude` CLI, version 2.1.76 or later	User scope, via `claude mcp add`
OpenAI Codex	`codex`	`codex` CLI	`~/.codex/config.toml` (or `$CODEX_HOME`), via `codex mcp add`
GitHub Copilot CLI	`copilot`	`copilot` CLI	`~/.copilot/mcp-config.json`, via `copilot mcp add`

NOTE

The Copilot target configures the copilot command-line agent; Steroid does not edit VS Code's own MCP settings. Other MCP clients are not automated setup targets.

Connecting an Agent

Use whichever is convenient — all three run the same setup:

First run: steroid → onboarding → Select your IDEs.
Later, in the app: steroid → Settings → IDE Connections → Set up or Re-configure.
From a script or terminal: steroid setup <target>.

Headless setup

steroid setup cursor
steroid setup claude-code
steroid setup codex
steroid setup copilot

Setup runs these steps in order and stops at the first one that fails:

#	Step	What it does
1	Check app	Cursor and Claude Code only: confirms the agent itself is installed.
2	Check CLI	Confirms the agent's command-line tool is on PATH (and the Claude Code version).
3	Write MCP config	Registers the `steroid` MCP server.
4	Write instructions	Adds Steroid's guidance for the agent (not used for Copilot).
5	Install skills	Copies Steroid's agent skills into the agent's skills folder.
6	Health probe	Asks the agent CLI to reply to a one-word prompt. A failure here is a warning, not a stop.

WARNING

Restart the agent when setup finishes. The MCP server's tool list is fixed when the agent starts it.

Exit code	steroid setup <target>
0	Wired
1	A blocking step failed
2	Unknown target

What Gets Written

Every agent gets the same server definition: the absolute path to the installed Steroid binary with the argument mcp-server. Cursor's file is written by Steroid; Claude Code, Codex and Copilot are configured through their own CLIs.

~/.cursor/mcp.json — the steroid entry

{
  "mcpServers": {
    "steroid": {
      "command": "/Users/you/.steroid/bin/steroid",
      "args": ["mcp-server"]
    }
  }
}

Other servers and keys in mcp.json are kept; the steroid entry is replaced. If the file is not valid JSON, it is moved aside to mcp.bak.<timestamp> and a new one is written.
For the other agents Steroid runs, for example, claude mcp add --scope user --transport stdio steroid -- <path> mcp-server.

Agent	Instructions	Skills folder
Cursor	`~/.cursor/rules/steroid-graph.mdc`	`~/.cursor/skills/`
Claude Code	Marked block in `~/.claude/CLAUDE.md`	`~/.claude/skills/`
OpenAI Codex	Marked block in `~/.codex/AGENTS.md`	`~/.codex/skills/`
GitHub Copilot CLI	None	`~/.copilot/skills/`

Local and Connected

The MCP entry is identical in both modes. The server reads the mode when it starts and registers a different tool set:

Mode	MCP tools	Skills installed
Local	3 — `recall_memory`, `recall_turn`, `recall_diff`	2
Connected	9 — the three above plus `search_tools`, `run_tool` and four workflow tools	4

Your connection string stays in Steroid's encrypted store under ~/.steroid/; the MCP server reads it when a Connected tool runs. After switching modes, restart the agent so it starts a server with the new tool set. See Local vs Connected Mode.

Checking the Connection

Read-only status check

steroid setup cursor --check --json

Healthy result (exit code 0)

{
  "ide": "cursor",
  "state": "connected",
  "ok": true,
  "checks": [ app, cli, mcp_wired, skills, health_probe ]
}

state	Exit code	Meaning
`connected`	0	CLI found, MCP entry present, health probe passed.
`partial`	3	Wired, but the health probe failed or was skipped with `--skip-health-probe`.
`disconnected`	1	The CLI or the MCP entry is missing.

NOTE

The health probe confirms the agent's CLI can answer a prompt — that it is installed and signed in. It does not start Steroid's MCP server. The final check is in the agent itself: after a restart, its MCP or tools list should show Steroid with 3 tools in Local mode or 9 in Connected.

steroid doctor gives a wider report: version, mode, skills for every agent, the Cursor MCP entry, and whether the background daemon is running.

Troubleshooting

Symptom	Cause	Fix
No Steroid tools after setup	The agent was not restarted	Restart the agent.
Wrong tools after changing mode	The running MCP server started under the old mode	Restart the agent.
`cli_not_found` or `app_not_found`	Agent not installed or not on PATH; Cursor needs both the app and `agent`	Install it using the link setup prints, then re-run setup.
Claude Code version error	Claude Code older than 2.1.76	Update Claude Code, then re-run setup.
`config_error`	Config or skills folder not writable, or `mcp add` timed out (15 s)	Fix permissions on the reported path and re-run — setup is safe to repeat.
Health probe: “Not signed in”	The agent CLI is not authenticated or has no credits	Run the agent CLI, sign in, re-check. Wiring is already done.
Recall answers are out of date	Background daemon not running, so indexes are not refreshed	`steroid daemon status`, then `steroid daemon start --force`.

Disconnecting an Agent

In the app, open Settings → IDE Connections → Disconnect. This removes Steroid's MCP entry, instructions block and skills from that agent, and deletes Steroid's recall index for it. There is no single-agent disconnect command; steroid uninstall removes Steroid from all four agents at once.

WARNING

Installing skills replaces a folder of the same name in the agent's skills directory. Uninstalling removes only folders Steroid installed.

→ Installation → Local vs Connected Mode → Agent Skills → Background Daemon