runbook mcp setup

GESF MCP Server Setup Runbook

Install the GESF MCP AI Compliance Assistant into any MCP-compatible client.

Prerequisites

Node.js >= 20.0.0 installed (node --version)
GESF installed globally (npm install -g @greenarmor/ges) or available via npx
At least one MCP-compatible client installed (see below)

!!! info "Windows users"

On Windows, `ges mcp setup` automatically writes **absolute paths** to `node.exe` and `npx.cmd` in the config. This avoids the common issue where VS Code can't find `npx` because it doesn't inherit your PowerShell PATH. No manual path lookup is needed when using `ges mcp setup`.

Option A — Automatic Setup (Recommended)

The ges mcp setup command auto-configures supported clients.

Install GESF

# Global install
npm install -g @greenarmor/ges

# Or use without installing
npx @greenarmor/ges mcp setup

Configure a single client

ges mcp setup claude       # Claude Desktop
ges mcp setup vscode       # VS Code (Copilot)
ges mcp setup cursor       # Cursor
ges mcp setup opencode     # OpenCode
ges mcp setup crush        # Crush
ges mcp setup windsurf     # Windsurf

Configure all clients at once

ges mcp setup all

Interactive mode

ges mcp setup
# Prompts you to select a client from a list

After setup, restart the target client to load the server.

Option B — Manual Setup (Per-Client)

If automatic setup is unavailable or you need custom configuration, follow the instructions for your client below.

1. Claude Desktop

Config file location:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Add this to the config file:

{
  "mcpServers": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"]
    }
  }
}

If the file already exists, merge the gesf entry into the existing mcpServers object. Do not overwrite other entries.

Reload: Quit and reopen Claude Desktop.

Verify: Open Claude Desktop settings → Developer → look for gesf in the MCP servers list.

2. VS Code (Copilot / GitHub Copilot Chat)

GESF can be configured at two levels in VS Code:

Option A — Global config (recommended, all projects)

Step 1: Open the VS Code Command Palette:

macOS: Cmd+Shift+P
Windows/Linux: Ctrl+Shift+P

Step 2: Type "MCP: Open User Configuration" and press Enter. This opens the global mcp.json.

Step 3: Add the server entry:

macOS / Linux:

{
  "servers": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"],
      "type": "stdio"
    }
  }
}

Windows:

VS Code may not find npx in its process PATH. Use the absolute path to npx.cmd:

# Find your npx path in PowerShell
where.exe npx
# Typical: C:\Program Files\nodejs\npx.cmd

{
  "servers": {
    "gesf": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@greenarmor/ges-mcp-server"],
      "type": "stdio"
    }
  }
}

!!! tip "Use ges mcp setup vscode on Windows"

Running `ges mcp setup vscode` (or `npx @greenarmor/ges mcp setup vscode`) **automatically detects the absolute path** to `npx.cmd` or `node.exe` and writes it into the config. No manual path lookup needed.

If the file already has content, merge the gesf entry into the existing servers object.

Or edit the file directly:

OS	Global config path
macOS	`~/Library/Application Support/Code/User/mcp.json`
Linux	`~/.config/Code/User/mcp.json`
Windows	`%APPDATA%\Code\User\mcp.json`

Option B — Project-level config (single project)

Run inside your project directory:

ges mcp setup vscode

This creates .vscode/mcp.json in the project root. GESF will only be available when that project is open.

Config content (same for both global and project-level):

{
  "servers": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"],
      "type": "stdio"
    }
  }
}

If the file already exists, merge the gesf entry into the existing servers object.

!!! danger "Do not use ${input:...} variables in mcp.json"

VS Code's `mcp.json` does **not** support `${input:...}` variable substitution or `"inputs"` arrays — those only work in `launch.json` and `tasks.json`. Adding them causes this error on startup:

> `CodeExpectedError: Variable 'cwd' must be defined in an 'inputs' section of the debug or task configuration.`

**Do NOT add these fields to `mcp.json`:**

- `"cwd"` — MCP servers inherit the workspace directory automatically
- `"envFile"` — not a valid MCP config field
- `"sandboxEnabled"` — not a standard MCP field
- `"dev"` — not a standard MCP field
- `"inputs"` array — only valid in `launch.json`/`tasks.json`

If you encounter this error, remove the invalid fields or re-run `ges mcp setup vscode` to regenerate a clean project-level config.

!!! warning "Not a VS Code extension"

GESF is an **MCP server**, not a VS Code extension. You will **not** find it on the VS Code Marketplace. Do not use VS Code's built-in NPM package installer (`Cmd+Shift+P` → "Install NPM Package") — it will ask for a "name" and "working directory" that are not related to MCP setup. Follow the steps above instead.

Reload: Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) → Developer: Reload Window.

Verify: Open Copilot Chat, switch to Agent mode, click the tools icon (🔨) — gesf should appear in the available tools list.

3. Cursor

Config file location:

Project-level: .cursor/mcp.json in your project root.

Add this to the config file:

{
  "mcpServers": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"]
    }
  }
}

If the file already exists, merge the gesf entry into the existing mcpServers object.

Reload: Quit and reopen Cursor.

Verify: Open Cursor settings → MCP → look for gesf in the active servers list.

4. OpenCode

Config file location:

Scope	Path
Project-level	`opencode.json` in project root
Global	`~/.config/opencode/opencode.json`

Add this to the config file:

{
  "mcp": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"],
      "type": "stdio"
    }
  }
}

If the file already exists, merge the gesf entry into the existing mcp object.

Reload: Restart OpenCode.

Verify: Run opencode and check that GESF tools appear when prompting the AI.

5. Crush

Config file location:

Global: ~/.local/share/crush/crush.json

Add this to the config file:

{
  "mcp": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"],
      "type": "stdio"
    }
  }
}

Important: Crush stores all configuration (providers, models, MCP servers) in a single crush.json file. Only add or modify the mcp.gesf entry — do not overwrite the rest of the file. The "type": "stdio" field is required by Crush's MCP format.

Reload: Restart Crush.

Verify: Run crush_info to confirm the GESF MCP server is connected, or ask any compliance question in a session.

6. Windsurf

Config file location:

Project-level: .windsurf/mcp.json in your project root.

Add this to the config file:

{
  "mcpServers": {
    "gesf": {
      "command": "npx",
      "args": ["-y", "@greenarmor/ges-mcp-server"]
    }
  }
}

If the file already exists, merge the gesf entry into the existing mcpServers object.

Reload: Quit and reopen Windsurf.

Verify: Open Windsurf settings → MCP → look for gesf in the active servers list.

Windows Absolute Path Reference

When manually editing MCP config files on Windows, use absolute paths instead of bare npx or node. Find them in PowerShell:

where.exe npx
where.exe node

How Node was installed	`npx.cmd` path	`node.exe` path
Official installer	`C:\Program Files\nodejs\npx.cmd`	`C:\Program Files\nodejs\node.exe`
nvm-windows	`C:\Users\<user>\AppData\Roaming\nvm\v<version>\npx.cmd`	`C:\Users\<user>\AppData\Roaming\nvm\v<version>\node.exe`
fnm	`%LOCALAPPDATA%\fnm_multishells\<version>\npx.cmd`	`%LOCALAPPDATA%\fnm_multishells\<version>\node.exe`

In JSON, double the backslashes:

"command": "C:\\Program Files\\nodejs\\npx.cmd"

!!! tip "Skip the manual work"

Running `ges mcp setup <client>` (or `npx @greenarmor/ges mcp setup <client>`) detects the absolute paths automatically. Use it instead of editing config files by hand.

Advanced — Custom Server Path (Source Build)

If you are developing GESF locally or installed from source, replace the npx command with a direct path to the built server:

{
  "mcpServers": {
    "gesf": {
      "command": "node",
      "args": ["/absolute/path/to/gesf/packages/mcp-server/dist/server.js"]
    }
  }
}

Or use the CLI command instead:

{
  "mcpServers": {
    "gesf": {
      "command": "node",
      "args": ["/absolute/path/to/gesf/packages/cli/dist/cli.js", "mcp", "start"]
    }
  }
}

Adapt the JSON key (mcpServers, servers, or mcp) and type field for your specific client as shown in the per-client sections above.

Available Tools (17 total)

Once configured, the GESF MCP server provides these tools to the AI assistant:

Compliance Assessment

Tool	Description	Parameters
`check_compliance`	Check GDPR compliance status for a project	`project_type` (string)
`check_project_status`	Read `.ges/` for real-time project status	`project_path` (string)
`list_missing_controls`	Show missing compliance controls for a framework	`framework` (string)
`list_framework_controls`	List all controls for a framework with status	`framework` (string)
`run_audit`	Run a full 6-scanner source code audit	`project_path` (string)
`generate_compliance_report`	Generate a full compliance report	`project_type`, `project_name`
`generate_audit_report`	Combine real audit findings with scoring	`project_path`, `project_name`

Fix & Implement

Tool	Description	Parameters
`auto_fix`	Automatically fix security findings in source code	`project_path`, `dry_run?`, `rule_ids?`
`implement_control`	Generate implementation files for a control	`project_path`, `control_id`
`apply_control_override`	Mark a control as not-applicable or pass	`project_path`, `control_id`, `status`, `reason`
`fix_recommendation`	Get step-by-step remediation guidance	`control_id` or `finding_title`

Document Generation

Tool	Description	Parameters
`generate_retention_policy`	Generate a data retention policy	`project_name`
`generate_incident_response`	Generate an incident response plan	`project_name`
`generate_risk_assessment`	Generate a risk assessment	`project_name`
`generate_dpa`	Generate a Data Processing Agreement	`project_name`
`generate_data_inventory`	Generate a data inventory with classifications	`project_name`, `project_type`
`generate_processing_records`	Generate Article 30 ROPA	`project_name`, `controller_name`

Example Prompts

After installing the MCP server, try these prompts in your AI client:

"Are we GDPR compliant?"
"Show me missing GDPR controls."
"Generate a retention policy for My SaaS App."
"Generate an incident response plan for Project Alpha."
"Generate a risk assessment for our healthcare platform."
"Generate a Data Processing Agreement for Customer Portal."
"Check compliance status for an AI application."

Verify the Server Works (Manual Test)

macOS / Linux:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n{"jsonrpc":"2.0","id":3,"method":"ping"}\n' | npx -y @greenarmor/ges-mcp-server

Windows (PowerShell):

$input = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' + "`n" + '{"jsonrpc":"2.0","method":"notifications/initialized"}' + "`n" + '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' + "`n"
$input | npx -y @greenarmor/ges-mcp-server

Expected: JSON responses for initialize and tools/list (17 tools listed). No output for the notification.

Troubleshooting

Problem	Cause	Fix
Server not found in client	Config file wrong location or bad JSON	Verify config file path from the table above; validate JSON syntax
`npx` fails or hangs	Stale cache or no network	Run `npx clear-npx-cache` then retry; or use `npm install -g @greenarmor/ges-mcp-server` and change command to `ges-mcp-server`
Tools not appearing	Client not reloaded	Restart the client completely (quit, not just close window)
`EACCES` permission error	Config directory not writable	Create the directory first: `mkdir -p <config-dir>`
Server crashes on start	Node.js too old	Verify `node --version` is >= 20.0.0
`Cannot find module`	Package not installed	Run `npm install -g @greenarmor/ges-mcp-server` or use `npx -y`
Multiple `gesf` entries	Re-ran setup	Manually edit config to keep only one `gesf` entry
Crush loses other config	Config overwritten	Only edit the `mcp.gesf` key, do not replace the entire file
Windows: `ges` not recognized after global install	npm global bin not in PATH	Run `npm config get prefix`, add that directory to PATH, or use `npx @greenarmor/ges` instead
Windows: `EBADENGINE` warning	Node.js < 20	Upgrade to Node 20+ via `winget install OpenJS.NodeJS.LTS`
Windows: MCP server fails to start in VS Code	VS Code can't find `npx` in its process PATH	Use absolute path to `npx.cmd` (see Windows section above), or run `ges mcp setup vscode` which auto-detects the path
Windows: MCP server silently fails (no error, no tools)	`node.exe` or `npx.cmd` not in VS Code's inherited PATH	Use `where.exe npx` in PowerShell to find the absolute path, put it in the `"command"` field
VS Code: `CodeExpectedError: Variable 'cwd' must be defined`	Invalid `${input:...}` variables or `inputs` section in `mcp.json`	Remove `cwd`, `envFile`, `sandboxEnabled`, `dev` fields and `inputs` section; or re-run `ges mcp setup vscode` to regenerate clean config
VS Code: can't find GESF on the Marketplace	GESF is an MCP server, not a VS Code extension	Add the server entry to your global or project `mcp.json` (see VS Code section above)
VS Code: NPM installer asks for "name" and "working directory"	VS Code's NPM package GUI is for NPM packages, not MCP servers	Cancel the installer and edit `mcp.json` directly (see VS Code section above)
VS Code: server not found after `ges mcp setup vscode`	Setup only creates project-level `.vscode/mcp.json`	For global availability, edit the global `mcp.json` instead (see Option A above)

Client Quick Reference

Client	Config File	JSON Key	Needs `type` Field	Scope
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `~/.config/Claude/claude_desktop_config.json` (Linux), `%APPDATA%\Claude\claude_desktop_config.json` (Windows)	`mcpServers`	No	Global
VS Code	`.vscode/mcp.json` (project) or global user `mcp.json` (see below)	`servers`	Yes (`"type": "stdio"`)	Project/Global
Cursor	`.cursor/mcp.json`	`mcpServers`	No	Project
OpenCode	`opencode.json` (project) or `~/.config/opencode/opencode.json` (global)	`mcp`	Yes (`"type": "stdio"`)	Project/Global
Crush	`~/.local/share/crush/crush.json`	`mcp`	Yes (`"type": "stdio"`)	Global
Windsurf	`.windsurf/mcp.json`	`mcpServers`	No	Project

VS Code global config paths:

OS	Path
macOS	`~/Library/Application Support/Code/User/mcp.json`
Linux	`~/.config/Code/User/mcp.json`
Windows	`%APPDATA%\Code\User\mcp.json`

Or open via Command Palette: Cmd+Shift+P / Ctrl+Shift+P → "MCP: Open User Configuration".

GESF Docs

📖 Full site →

Uh oh!

runbook mcp setup

GESF MCP Server Setup Runbook

Prerequisites

Option A — Automatic Setup (Recommended)

Install GESF

Configure a single client

Configure all clients at once

Interactive mode

Option B — Manual Setup (Per-Client)

1. Claude Desktop

2. VS Code (Copilot / GitHub Copilot Chat)

Option A — Global config (recommended, all projects)

Option B — Project-level config (single project)

3. Cursor

4. OpenCode

5. Crush

6. Windsurf

Windows Absolute Path Reference

Advanced — Custom Server Path (Source Build)

Available Tools (17 total)

Compliance Assessment

Fix & Implement

Document Generation

Example Prompts

Verify the Server Works (Manual Test)

Troubleshooting

Client Quick Reference

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GESF Docs

Clone this wiki locally