@ignitetech/gensym-mcp

AI-powered copilot for Gensym. Provides 40+ tools for searching Gensym documentation, analyzing knowledge bases, generating Gensym code, and exporting KB contents — all accessible from your AI coding assistant.

Migrating from @ignitetech/g2-mcp? This package was previously published as @ignitetech/g2-mcp. Update the args entry in your MCP client config to @ignitetech/gensym-mcp (and optionally rename the server key from g2-mcp to gensym-mcp). The old name has been deprecated on npm.

Prerequisites

• Node.js 18+
• Gensym installation (required only for KB export — documentation and search tools work without it)
• API key provided by your administrator

Setup

Add the following to your MCP client configuration (Cursor, Claude Desktop, Windsurf, etc.):

{
  "mcpServers": {
    "gensym-mcp": {
      "command": "npx",
      "args": [
        "@ignitetech/gensym-mcp",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<your-api-key>",
        "GENSYM_ROOT": "C:\\g2-2023-64\\g2"
      }
    }
  }
}

If you only need documentation and search tools (no KB export), you can omit GENSYM_ROOT:

{
  "mcpServers": {
    "gensym-mcp": {
      "command": "npx",
      "args": [
        "@ignitetech/gensym-mcp",
        "https://g2mcp.ignitetech.ai/mcp/",
        "--header",
        "X-API-KEY:${GENSYM_MCP_API_KEY}"
      ],
      "env": {
        "GENSYM_MCP_API_KEY": "<your-api-key>"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GENSYM_MCP_API_KEY | Yes | API key for the Gensym MCP server | | GENSYM_ROOT | For KB export & local analysis | Path to your Gensym installation directory (e.g., C:\g2-2023-64\g2 or /opt/g2/g2). When set, the proxy exposes local KB export and analysis tools that operate on your machine's KB exports. | | GENSYM_API_URL | For write-enabled mode | Base URL of a running Gensym API server (default: http://localhost:8082). When set, the proxy exposes compile / CRUD / save / merge tools that operate on a live Gensym instance. | | GENSYM_EXPORT_PATH | Optional | Override for the export file location. Defaults to <target-kb-dir>/g2-mcp-export.js (same directory as the source KB). Must resolve inside GENSYM_ROOT — export write paths are contained to the Gensym root. | | GENSYM_ALLOW_WRITE | Optional | Secure by default: write tools are DISABLED unless you opt in. Set to a truthy value (true/1/yes/on) to enable write tools (compile_gensym_code, create_gensym_*, update_gensym_item, delete_gensym_item, run_gensym_procedure, save_gensym_kb, save_gensym_kb_module, merge_gensym_kb). | | GENSYM_READ_ONLY | Optional | The proxy is read-only by default. Explicitly set this to a falsy value (false/0/no/off) to enable write tools (equivalent to GENSYM_ALLOW_WRITE=true). A truthy value keeps read-only. Precedence: a truthy GENSYM_READ_ONLY is the kill-switch and always wins — it can never be overridden by GENSYM_ALLOW_WRITE, so with both set truthy the proxy stays read-only. Parsing is case-insensitive. | | GENSYM_TELEMETRY | Optional | Off by default. Set to a truthy value (true/1/yes/on) to enable per-call usage reporting to the hosted server. Every transmitted field is bounded to a non-free-form value (see the complete list below). No free-form tool output, G2 server message, error text, KB source, filename, or filesystem path is ever transmitted. |

Telemetry payload (when GENSYM_TELEMETRY is enabled)

When — and only when — telemetry is enabled, each tool call POSTs a fixed-shape body to the hosted server. This is the complete list of transmitted fields; every one is bounded by construction:

| Field | Value | Why it is safe | |-------|-------|----------------| | tool_name | The MCP tool's name (e.g. compile_gensym_code) | Fixed tool-name set; not user- or server-controlled. | | arguments | Redacted argument object | redactArguments() keeps only numbers, booleans, and a small allowlist of enum-like string keys (type, element_type, direction, overlay, kb_glob). Customer G2 source (text), filenames, queries, and filesystem paths (target_kb, output_dir, path, …) are dropped. | | status | "ok" or "failed" | Two-value enum. | | result_summary | Output size in MB (e.g. "12.5 MB") when a numeric byte size is present, otherwise the status token ("ok"/"failed") | Bounded by boundedResultSummary(). The G2 server's free-form result.message / result.status — which can embed paths or KB content — are never sent. | | duration_ms | Numeric wall-clock timing | A number; carries no content. | | error_category | On failure, a bounded, identifier-shaped token (e.g. TypeError, AbortError, or the generic ToolError) | Bounded by errorCategory(). The raw error message is never sent, so filesystem paths (including paths containing spaces) cannot leak through error text. | | source | Constant "g2-mcp-proxy" | Fixed literal. | | source_version | The proxy version (e.g. "0.1.0") | Fixed literal. | | platform | os.platform() (e.g. darwin, linux, win32) | Fixed OS enum. |

No other fields are transmitted. In particular, no free-form tool output, no G2 server message, no error text, no KB source, no filename, and no filesystem path is ever part of the telemetry body.

Breaking change (security): the proxy is now read-only by default. Previously write tools were exposed unless GENSYM_READ_ONLY="true" was set (fail-open). To restore write access, set GENSYM_ALLOW_WRITE=true (or GENSYM_READ_ONLY=false).

What You Can Do

Once configured, ask your AI assistant to:

• Search documentation — "How do I create a rule in Gensym?"
• Generate Gensym code — "Write a procedure that calculates average temperature"
• Analyze your KB — "Show me a summary of my knowledge base"
• Find dependencies — "What procedures does calculate-flow call?"
• Export a KB — "Export the g2-copilot knowledge base"

Troubleshooting

Tools not loading Verify your API key is correct and that the server URL in your config is reachable.

KB export not working Ensure GENSYM_ROOT points to your Gensym installation directory and that the target KB path is correct.

Support

Contact your Gensym administrator for API keys and support.