Setup Instructions

Connect Cursor IDE, Claude Code, or Claude Desktop to the Gensym MCP Server using the @ignitetech/g2-mcp npm proxy.

On this page

Prerequisites

  • Node.js 18+ — required to run the proxy via npx.
  • API key — an IgniteTech-issued X-API-KEY. Request access if you don't have one.
  • Gensym installation — only needed for KB export (set GENSYM_ROOT) or to run a live Gensym locally for write-enabled mode. Documentation, search, and codebase analysis on existing exports work without Gensym.
Note: GENSYM_API_URL (write-enabled mode) and GENSYM_ROOT (KB export) are independent. You can use either, both, or neither — pick whatever matches your workflow.

Environment reference

The full set of environment variables the proxy reads. Set these in the env block of your MCP client config.

Variable Required Purpose
GENSYM_MCP_API_KEY Always Authenticates the proxy with the hosted MCP server. Validated on startup — the proxy exits if the key is invalid or revoked.
GENSYM_API_URL Write-enabled Where the proxy reaches the local Gensym API server that powers Write-enabled mode. The default http://localhost:8082 is correct for almost everyone. Set this only if you've changed the API server's port (e.g. it's already running on 8083). The API server runs on your own machine — there's no remote URL to point at.
GENSYM_ROOT For KB export Path to your Gensym installation (e.g. C:\g2-2023-64\g2 or /opt/g2/g2). Unlocks export_kb_via_remote_inspect, export_and_analyze_kb_folder, and start_gensym_api_server / stop_gensym_api_server.
GENSYM_EXPORT_PATH Optional Override the default export file location. Defaults to <target-kb-dir>/g2-mcp-export.js.
🔒 Mode 1

Read-only

For documentation, search, and codebase analysis on existing exports. The AI cannot mutate Gensym because no live Gensym endpoint is configured — the write tools are simply not exposed.

Configuration

{
  "mcpServers": {
    "g2-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

✓ Available

  • 12 documentation tools (Reference, Tutorials, System Procedures)
  • 7 codebase analysis tools (on prior exports)
  • 2 visualization & analytics tools
  • get_gensym_guide, list_pdfs, health

✕ Not available

  • All compile_gensym_code / item CRUD tools
  • save_gensym_kb, merge_gensym_kb
  • get_gensym_attribute, list_active_rules
  • get_gensym_logbook, get_gensym_messages
Where analysis runs: codebase analysis tools (get_kb_summary, search_kb_elements, detect_bottlenecks, etc.) run against the hosted server's KB index by default. To run them against your own local exports — including get_dependency_diagram and get_kb_statistics — add GENSYM_ROOT to the env block (the proxy then routes those calls to your machine instead of the hosted server). See the KB export add-on below.
✏️ Mode 2

Write-enabled

For agentic development against a live Gensym server. Adds compile, create, update, save, and merge against a Gensym instance running on your machine.

Configuration

{
  "mcpServers": {
    "g2-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>",
        "GENSYM_API_URL": "http://localhost:8082"
      }
    }
  }
}

✓ Adds (on top of Read-only)

  • compile_gensym_code — validate against a live parser
  • create_gensym_workspace, create_gensym_item
  • get_gensym_item, update_gensym_item, delete_gensym_item
  • save_gensym_kb, merge_gensym_kb
  • get_gensym_attribute, list_active_rules
  • get_gensym_logbook, get_gensym_messages

⚙️ Prerequisite

A running Gensym with g2-api-server.kb listening on the URL above. See Live Gensym prerequisites — if you also set GENSYM_ROOT, the AI can spawn it for you with start_gensym_api_server.

Heads up: Write-enabled mode lets the AI modify your knowledge base. Use a non-production KB for experimentation, or stay in Read-only mode if you're not ready for the AI to make changes.

📦 Optional: KB export add-on

Setting GENSYM_ROOT is independent of the read-only / write-enabled choice — it works on top of either mode. It points the proxy at your Gensym installation so it can spawn Gensym processes locally to dump knowledge bases to JSON.

Add to your env block

"env": {
  "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>",
  "GENSYM_ROOT": "C:\\g2-2023-64\\g2"
}

Tools this unlocks

  • export_kb_via_remote_inspect — export a single KB to a structured codebase directory
  • export_and_analyze_kb_folder — batch export every KB in a folder
  • start_gensym_api_server / stop_gensym_api_server — auto-spawn the Gensym API server for write-enabled mode
On macOS / Linux, use the matching forward-slash path for GENSYM_ROOT (e.g. /opt/g2/g2).

Per-IDE config formats

The proxy is the same across all clients. The only differences are: where the config file lives, and (on Windows for Claude) the need to wrap npx in cmd /c. Drop your Mode 1 or Mode 2 env block from above into the snippet for your IDE.

Cursor IDE

Config file: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

Cross-platform configuration

{
  "mcpServers": {
    "g2-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
Works on macOS, Linux, and Windows — Cursor invokes npx natively on all platforms. Add GENSYM_API_URL for Mode 2, or GENSYM_ROOT for KB export, inside the env block.

Claude Code

Config file: ~/.claude.json (user) or .mcp.json (project) 
{
  "mcpServers": {
    "g2-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
{
  "mcpServers": {
    "g2-mcp": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
On Windows, Claude Code cannot invoke npx directly — the cmd /c wrapper is required.
Add GENSYM_API_URL for Mode 2, or GENSYM_ROOT for KB export, inside the env block.

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "g2-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
macOS tip: If Claude Desktop reports npx not found, your GUI environment may not include Homebrew or nvm paths. Replace "command": "npx" with the full path, e.g. "command": "/opt/homebrew/bin/npx" or "command": "/usr/local/bin/npx". Run which npx in Terminal to find the correct path.
Config file: %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "g2-mcp": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y",
        "@ignitetech/g2-mcp@latest",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
On Windows, Claude Desktop cannot invoke npx directly — the cmd /c wrapper is required.
Add GENSYM_API_URL for Mode 2, or GENSYM_ROOT for KB export, inside the env block. Restart Claude Desktop after saving the config.

Live Gensym prerequisites (Mode 2 only)

Write-enabled mode talks to a small HTTP API exposed by a Gensym instance running on your machine. The API is provided by g2-api-server.kb, which ships with the proxy and listens on port 8082 by default.

Two ways to start it

  • Auto (recommended) — if you also set GENSYM_ROOT, ask the AI to call start_gensym_api_server. The proxy deploys g2-api-server.kb to <GENSYM_ROOT>/kbs/, spawns Gensym with -start, and waits for the port to come up. stop_gensym_api_server tears it down.
  • Manual — start G2 yourself with g2-api-server.kb loaded, listening on http://localhost:8082 (or whatever URL you configure as GENSYM_API_URL).
Once the server is running, compile_gensym_code, item CRUD, save/merge, and the live read tools (get_gensym_attribute, list_active_rules, get_gensym_logbook, get_gensym_messages) become available automatically.

Troubleshooting

Auth failure on startup

The proxy exits with "API key invalid/expired" or similar. Check GENSYM_MCP_API_KEY is set correctly with no whitespace. If the key was ever shared outside your machine, contact your IgniteTech admin to rotate it.

Tools not loading at all

Check that your mcp.json parses (no trailing commas), that the server URL https://g2mcp.ignitetech.ai/mcp/ is reachable from your machine, and that Node 18+ is on the PATH the IDE uses.

Expected write-enabled tools are missing

Either GENSYM_API_URL is not set, or the Gensym API server is not running on that URL. Switch to the Mode 2 config above and start the API server — start_gensym_api_server if GENSYM_ROOT is set, otherwise launch it manually.

KB export not working

Ensure GENSYM_ROOT points to your Gensym installation directory and that the target KB path is given relative to GENSYM_ROOT (e.g. kbs/g2-copilot.kb). Increase export_timeout_seconds for very large KBs.

macOS: npx not found

Claude Desktop launches outside your shell, so it may not see Homebrew or nvm paths. Replace "command": "npx" with the full path — run which npx in Terminal to find it (/opt/homebrew/bin/npx or /usr/local/bin/npx).

Key handling & security

  • Do not commit API keys into git. Use environment variables or ${VAR} placeholders in config files.
  • The proxy's ${GENSYM_MCP_API_KEY} syntax is expanded at runtime from the env block — your key never appears in the args.
  • If a key has ever been shared outside your machine, contact your IgniteTech admin to have it rotated.
← Back to landing page • Request API access