Installation & Setup

Supported environments

# 1. Add marketplace source & install plugin
claude plugin marketplace add seedlinglabs/forgebench-plugin
claude plugin install forgebench@forgebench

# 2. Start Claude Code. In the active session, ask your agent to run /reload-plugins.
# 3. Run /mcp and choose 'forgebench' -> 'Authenticate'
claude

// Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
  "forgebench": {
    "url": "https://api.forgebench.ai/mcp",
    "auth": {
      "CLIENT_ID": "forgebench-cursor",
      "scopes": ["forgebench:read", "forgebench:write"]
    }
  }
}
}

# 1. Add the server (writes to ~/.codex/config.toml)
codex mcp add forgebench --url https://api.forgebench.ai/mcp --oauth-client-id forgebench-codex

# 2. Sign in (opens your browser)
codex mcp login forgebench

# Or add this to ~/.codex/config.toml by hand, then run step 2:
# [mcp_servers.forgebench]
# url = "https://api.forgebench.ai/mcp"
# oauth_resource = "https://api.forgebench.ai/mcp"
# default_tools_approval_mode = "writes"
#
# [mcp_servers.forgebench.oauth]
# client_id = "forgebench-codex"
#
# [mcp_servers.forgebench.tools.forgebench_apply_plan]
# approval_mode = "prompt"

// Add to .vscode/mcp.json (workspace), or run "MCP: Open User Configuration"
{
"servers": {
  "forgebench": {
    "type": "http",
    "url": "https://api.forgebench.ai/mcp",
    "oauth": { "clientId": "forgebench-vscode" }
  }
}
}

// Add to ~/.config/opencode/opencode.json (all projects) or opencode.json (one project)
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
  "forgebench": {
    "type": "remote",
    "url": "https://api.forgebench.ai/mcp",
    "oauth": { "clientId": "forgebench-opencode" }
  }
}
}

// Then sign in (opens your browser):
// opencode mcp auth forgebench

Install with the CLI

forgebench mcp writes the server entry from the tabs above for Claude Code, OpenCode and Cursor, so you don't edit the files by hand. It writes no key or token: you sign in with OAuth in the tool, as in step 2 below.

forgebench mcp install     # this repository's config; run it inside a git repository
forgebench mcp status      # what is installed, in the project and user scope
forgebench mcp remove      # removes only the entries `install` wrote

| Flag | Effect | | --- | --- | | --tool claude\|opencode\|cursor | Limit to one tool. Repeat it for several. Without it, every tool found on the machine is used. | | --scope project\|user | project (default) writes .mcp.json, opencode.json and .cursor/mcp.json in the repository and never commits them. user writes your own config. status reports both unless you name one. | | --forgebench-url <url> | The MCP URL is this URL plus /mcp. The default is the control plane the CLI uses (https://api.forgebench.ai unless you set FORGEBENCH_URL). | | --dry-run | Show what would change and write nothing. |

Set FORGEBENCH_MCP_URL to use a different MCP URL, for example http://localhost:8000/mcp for a local stack. It must be a plain http(s) URL with no credentials or query string.

Running install again changes nothing. remove deletes only the entries install wrote, for the URL it would write: an entry you edited, or one that points at another URL, is left alone with a message. install also leaves an entry you edited, or one that points at another URL, alone and exits with 1. A file that is not valid JSON, or whose server section is not an object, is left untouched and reported. OpenCode comments and formatting are preserved.

On OpenCode, mcp install and mcp remove write and remove the direct mcp.forgebench entry with its forgebench-opencode client id, in both scopes, whether or not the @forgebench/opencode plugin is installed. They never create or change the plugin entry or its options. If the plugin entry already has its mcp option on, mcp install warns and writes nothing, because the endpoint would be registered twice; mcp status reports the same clash. Turn the option off in the plugin entry of your OpenCode config first.

Claude Code is registered with claude mcp add --transport http, with no client id so the server can ask for more access when a tool needs it. The forgebench plugin can also supply this server through its mcp_url option, which is global (Claude's user scope). The CLI never registers the same endpoint twice, and it never changes the plugin's session sync options. Only mcp_url changes.

With --scope user:

• Plugin installed by the CLI (forgebench hooks install): install sets mcp_url and remove clears it. If you turned session sync off, clearing mcp_url also removes the plugin, because nothing needs it any more. A plugin that is disabled in Claude Code is refused with the claude plugin enable command, which also resumes session sync when sync is on.
• Plugin you installed yourself: it is reused only when its mcp_url already matches. Otherwise, with an empty mcp_url, the CLI adds a claude mcp add --scope user server and leaves the plugin alone. remove never clears an mcp_url the CLI did not set. An mcp_url that points elsewhere makes install exit with 1.
• No plugin: claude mcp add --scope user.

With --scope project, a plugin that already supplies the same URL is reused and nothing is added to .mcp.json. Otherwise the CLI adds the project entry and leaves the plugin option alone. Teammates are asked to approve a project-scoped Claude Code server the first time they open the repository.

status never starts a sign-in, so it reports authorization as not checked. Restart the tool, then sign in as described in step 2.

Step-by-step setup

1. Install the plugin or add the server

   In Claude Code, run:

   claude plugin marketplace add seedlinglabs/forgebench-plugin
   claude plugin install forgebench@forgebench

   Then ask Claude Code to run /reload-plugins to load the plugin in the current session.

   In Cursor, Codex, VS Code or OpenCode, add the server with the config from the matching tab above. Keep the forgebench-cursor, forgebench-codex, forgebench-vscode or forgebench-opencode client id: Forgebench only accepts sign-ins from these registered clients, so a server entry without one fails to authenticate.

2. Sign in with OAuth

   1. Start the sign-in:
      • Claude Code: run /mcp, select forgebench, and choose Authenticate.
      • Cursor: open Cursor Settings → Tools & MCP. forgebench is listed as Needs authentication; click Connect.
      • Codex: run codex mcp login forgebench.
      • VS Code: run MCP: List Servers, select forgebench, and choose Start Server. VS Code opens a browser window to sign in on the first connection.
      • OpenCode: run opencode mcp auth forgebench. Check the result with opencode mcp list.
   2. Sign in on the browser page that opens, select your workspace, and approve access.

3. Verify connection

   Type in chat:

   "Who am I in Forgebench?"

   Your assistant shows your active workspace, your role and the default agent policies.

Troubleshooting setup issues

No forgebench tools available, or tools not responding. Ask Claude Code to run /reload-plugins. Then run /mcp, select forgebench, and check that it shows as connected. If authentication expired, choose Authenticate.

Connected to the wrong workspace. Each MCP session is bound to one workspace. Run /mcp, select forgebench, re-authenticate, and pick the workspace from the organization picker.

Scanner requires Python 3.10+. If your default python3 is older (macOS ships 3.9), install a newer one, for example brew install python@3.12, and make sure it's on your $PATH.

Next