Client Setup¶

Every AI tool below starts PPEE the same way: it runs ppee-cli --mcp as a child process and talks to it over stdin/stdout. What differs is where each tool keeps its configuration and how you check that it worked. Find your tool in the table, then follow its section.

Before you start¶

1. Get ppee-cli 2.0.0 or newer (install) and check that MCP mode is there:

$ ppee-cli --help | grep mcp
       ppee-cli --mcp [--mcp-allow-write]
  --mcp                  run as a Model Context Protocol server on stdin/stdout
  --mcp-allow-write      with --mcp: also expose the patch_pe (write) tool

2. Note the absolute path to the executable. Tools rarely inherit your shell's PATH, so a bare ppee-cli often fails.

Optional: keep Suspicious.txt in the same folder as ppee-cli. It is the keyword list behind the suspicious strings group (get_strings); without it that group is empty and the response says so (suspiciousNote). Builds and the container image put it there already.

3. Test the server outside any AI tool (30 seconds, saves a lot of guessing):

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | /opt/ppee/ppee-cli --mcp

'{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | C:\Tools\ppee\ppee-cli.exe --mcp

You should see a ready on stdio line on stderr and a JSON reply listing the tools. If not, fix this first; no client will do better.

Claude Desktop¶

Windows and macOS. Claude Desktop is not offered on Linux; use Claude Code there.

1. Open Settings → Developer and click Edit Config. This opens (or creates) claude_desktop_config.json:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the ppee server:

   WindowsmacOS (Docker)

   %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "ppee": {
         "command": "C:\\Tools\\ppee\\ppee-cli.exe",
         "args": ["--mcp"]
       }
     }
   }
   

   ~/Library/Application Support/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "ppee": {
         "command": "docker",
         "args": ["run", "--rm", "-i", "--network", "none",
                  "-v", "/Users/me/samples:/samples:ro",
                  "ppee-cli", "--mcp"]
       }
     }
   }
   

   If the file already has other servers, add ppee next to them inside the same mcpServers object. 3. Quit Claude Desktop completely (not just close the window) and start it again. 4. In a new chat, open the Add files, connectors, and more control near the message box, go to Connectors, and confirm ppee is listed with its tools.

If it doesn't show up: open the logs (%APPDATA%\Claude\logs on Windows, ~/Library/Logs/Claude on macOS). mcp.log records connection failures, and mcp-server-ppee.log holds PPEE's stderr, where you should find MCP server ready on stdio. Claude asks for your approval before each tool call; approving get_hashes or check_signature is fine, but read the security model before allowing anything that writes.

Official guide: Connect to local MCP servers

Claude Code¶

Windows, Linux, macOS (terminal). Two rules from the CLI: put options before the server name, and put -- before the server command so --mcp goes to PPEE instead of being read by claude.

# available in every project of your user
claude mcp add --scope user ppee -- /opt/ppee/ppee-cli --mcp

# or only for the current project, kept private (default scope)
claude mcp add ppee -- /opt/ppee/ppee-cli --mcp

# or shared with the team through the repo (writes .mcp.json)
claude mcp add --scope project ppee -- /opt/ppee/ppee-cli --mcp

claude mcp add --scope user ppee -- C:\Tools\ppee\ppee-cli.exe --mcp

claude mcp add --scope user ppee -- docker run --rm -i --network none -v "$PWD:$PWD:ro" ppee-cli --mcp

Check it:

claude mcp list          # shows ppee and whether it connects
claude mcp get ppee      # the stored command

Inside a session, type /mcp to see the status (✔ Connected, ✘ Failed) and tool counts, and to disable or enable the server for that project.

• A project-scoped server from .mcp.json asks for your approval the first time; claude mcp reset-project-choices asks again.
• Already set up Claude Desktop? claude mcp add-from-claude-desktop imports its servers.
• Prefer JSON? claude mcp add-json ppee '{"command":"/opt/ppee/ppee-cli","args":["--mcp"]}'

Official guide: Claude Code MCP

Visual Studio Code (GitHub Copilot)¶

1. Run MCP: Add Server from the Command Palette (Ctrl+Shift+P) and choose the local command (stdio) option, or edit the file directly. Pick Workspace to share it with the repo or Global for all workspaces (MCP: Open User Configuration opens the global file).

2. The file is .vscode/mcp.json (top-level key servers):

   WindowsLinux

   .vscode/mcp.json

   {
     "servers": {
       "ppee": {
         "type": "stdio",
         "command": "C:\\Tools\\ppee\\ppee-cli.exe",
         "args": ["--mcp"]
       }
     }
   }
   

   .vscode/mcp.json

   {
     "servers": {
       "ppee": { "type": "stdio", "command": "/opt/ppee/ppee-cli", "args": ["--mcp"] }
     }
   }
   

3. The first time the server starts, VS Code shows a trust dialog. Select the link to review the command, then confirm.

4. Open the Chat view, switch to Agent mode, and select Configure Tools in the chat input: the ppee tools should be listed, and you can switch individual ones off (for example patch_pe).

Command-line shortcut:

code --add-mcp '{"name":"ppee","command":"/opt/ppee/ppee-cli","args":["--mcp"]}'

Official guide: MCP servers in VS Code

GitHub Copilot in other IDEs¶

Copilot in JetBrains IDEs, Visual Studio, Xcode and Eclipse supports local stdio servers with the same mcp.json shape as VS Code (top-level servers). Open the IDE's Copilot MCP configuration and add:

{
  "servers": {
    "ppee": {
      "command": "C:\\Tools\\ppee\\ppee-cli.exe",
      "args": ["--mcp"]
    }
  }
}

In Visual Studio add "type": "stdio" to the entry. Then start a Copilot Chat in agent mode and check that the ppee tools are offered. The organization policy in the VS Code section applies here too.

Official guide: Extend Copilot Chat with MCP

Cursor¶

1. Create the config file. Per project: .cursor/mcp.json in the project root. For every project: ~/.cursor/mcp.json (on Windows, %USERPROFILE%\.cursor\mcp.json).

2. Add the server (top-level key mcpServers):

   .cursor/mcp.json

   {
     "mcpServers": {
       "ppee": {
         "command": "C:\\Tools\\ppee\\ppee-cli.exe",
         "args": ["--mcp"]
       }
     }
   }
   

3. Open Cursor's MCP settings (in the sidebar's Customize area in current versions) and make sure the ppee toggle is on. A disabled server doesn't load and its tools don't appear in chat.

4. Ask something in Agent chat. To see what happened, open the Output panel (Ctrl+Shift+U) and pick MCP Logs.

Official guide: Cursor MCP

Windsurf¶

1. In the Cascade panel, click the … (Actions) menu and choose Open MCP config file. This opens the right file for your version; on current builds it is ~/.config/devin/mcp_config.json (macOS/Linux) or %APPDATA%\devin\mcp_config.json (Windows).

2. Add the server (top-level key mcpServers):

   mcp_config.json

   {
     "mcpServers": {
       "ppee": {
         "command": "C:\\Tools\\ppee\\ppee-cli.exe",
         "args": ["--mcp"]
       }
     }
   }
   

3. Save the file. Changes take effect on save; there is no marketplace or one-click install for custom servers, so this manual edit is the way.

Official guide: Cascade MCP

Cline¶

The Cline extension for VS Code.

1. Open the Cline panel and click the MCP Servers icon in its top toolbar.
2. Go to the Configure tab and click Configure MCP Servers. This opens cline_mcp_settings.json.

3. Add the server:

   cline_mcp_settings.json

   {
     "mcpServers": {
       "ppee": {
         "command": "C:\\Tools\\ppee\\ppee-cli.exe",
         "args": ["--mcp"],
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

4. Save. The server appears in the MCP Servers panel; run a small request to confirm.

Official guide: Configuring MCP servers in Cline

Zed¶

Zed calls MCP servers context servers. Open your settings (zed: open settings) and add:

{
  "context_servers": {
    "ppee": {
      "command": "/opt/ppee/ppee-cli",
      "args": ["--mcp"],
      "env": {}
    }
  }
}

Verify in Settings → AI → MCP Servers (or run agent: open settings and pick MCP Servers): a green dot with the tooltip Server is active means it is running. Other colors or tooltips explain what failed.

Official guide: MCP in Zed

Continue¶

Add PPEE under mcpServers in config.yaml (a file under .continue/mcpServers/ works too; see Continue's docs for its file header):

mcpServers:
  - name: ppee
    type: stdio
    command: /opt/ppee/ppee-cli
    args:
      - "--mcp"

Official guide: MCP in Continue

Gemini CLI¶

Edit ~/.gemini/settings.json (for all projects) or .gemini/settings.json (this project only):

{
  "mcpServers": {
    "ppee": {
      "command": "/opt/ppee/ppee-cli",
      "args": ["--mcp"],
      "trust": false
    }
  }
}

Then check it:

gemini mcp list        # from the shell: connection status and tools
/mcp                   # the same, inside a Gemini session

Official guide: Gemini CLI MCP servers

OpenAI Codex CLI¶

codex mcp add ppee -- /opt/ppee/ppee-cli --mcp
codex mcp list

[mcp_servers.ppee]
command = "/opt/ppee/ppee-cli"
args = ["--mcp"]

[mcp_servers.ppee]
command = 'C:\Tools\ppee\ppee-cli.exe'
args = ["--mcp"]

The file is ~/.codex/config.toml; a project can carry its own .codex/config.toml if the project is trusted. codex mcp --help lists the other subcommands.

Official guide: Codex MCP

opencode¶

opencode's format differs from most tools: the executable and its arguments go together in one command array, and each entry needs "type": "local".

1. Create or edit the config: opencode.json (or opencode.jsonc) in the project root for one project, or the global config in ~/.config/opencode/.

2. Add the server under the top-level mcp key:

   WindowsLinuxDocker

   opencode.json

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "ppee": {
         "type": "local",
         "command": ["C:\\Tools\\ppee\\ppee-cli.exe", "--mcp"],
         "enabled": true
       }
     }
   }
   

   opencode.json

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "ppee": {
         "type": "local",
         "command": ["/opt/ppee/ppee-cli", "--mcp"],
         "enabled": true
       }
     }
   }
   

   opencode.json

   {
     "mcp": {
       "ppee": {
         "type": "local",
         "command": ["docker", "run", "--rm", "-i", "--network", "none",
                     "-v", "/home/me/samples:/samples:ro", "ppee-cli", "--mcp"],
         "enabled": true
       }
     }
   }
   

3. Start opencode and check the server: opencode mcp list shows the registered servers and their status.

"enabled": false keeps the entry without loading it. To use --mcp-allow-write, add it as another element of the command array (["…/ppee-cli", "--mcp", "--mcp-allow-write"]).

Official guide: opencode MCP servers

Kilo Code¶

Kilo Code (the VS Code and JetBrains extension, and the kilo CLI) uses the same format as opencode: one command array holds the executable and its arguments, under a top-level mcp key, with "type": "local".

1. Open the config in either of these ways:
   • From the UI: Settings (gear icon) → Agent Behaviour → MCP Servers → Add Server → Local (stdio).
   • By editing the file: kilo.jsonc in the project root (or .kilo/kilo.jsonc) for one project, or ~/.config/kilo/kilo.jsonc for all projects.

2. Add the server:

   WindowsLinuxDocker

   kilo.jsonc

   {
     "mcp": {
       "ppee": {
         "type": "local",
         "command": ["C:\\Tools\\ppee\\ppee-cli.exe", "--mcp"],
         "enabled": true
       }
     }
   }
   

   kilo.jsonc

   {
     "mcp": {
       "ppee": {
         "type": "local",
         "command": ["/opt/ppee/ppee-cli", "--mcp"],
         "enabled": true
       }
     }
   }
   

   kilo.jsonc

   {
     "mcp": {
       "ppee": {
         "type": "local",
         "command": ["docker", "run", "--rm", "-i", "--network", "none",
                     "-v", "/home/me/samples:/samples:ro", "ppee-cli", "--mcp"],
         "enabled": true,
         "timeout": 30000
       }
     }
   }
   

3. Check the server under Settings → Agent Behaviour → MCP Servers. A failed status means the server didn't start: check the path, and run the command by hand (see Testing without an AI tool).

The default start-up timeout for local servers is 10 seconds (10000 ms). Raise it for Docker, as in the example above, if the image has to start first.

Auto-approval. Kilo Code approves tools through the top-level permission key, by name in the form <server>_<tool>. Approve only the read-only tools, and never ppee_patch_pe or a ppee_* wildcard if the server runs with --mcp-allow-write:

{
  "permission": {
    "ppee_triage_pe": "allow",
    "ppee_list_imports": "allow"
  }
}

To use --mcp-allow-write, add it to the command array (["…/ppee-cli", "--mcp", "--mcp-allow-write"]).

Official guide: Using MCP in Kilo Code

OpenClaw¶

OpenClaw runs MCP servers from its Gateway process, and saves them under mcp.servers in the OpenClaw configuration (not in separate files).

openclaw mcp add ppee --command /opt/ppee/ppee-cli --arg --mcp

openclaw mcp set ppee '{"command":"/opt/ppee/ppee-cli","args":["--mcp"],"transport":"stdio"}'

{
  mcp: {
    servers: {
      ppee: {
        command: "/opt/ppee/ppee-cli",
        args: ["--mcp"],
        transport: "stdio",
        enabled: true,
      },
    },
  },
}

openclaw mcp set ppee '{"command":"docker","args":["run","--rm","-i","--network","none","-v","/home/me/samples:/samples:ro","ppee-cli","--mcp"],"transport":"stdio"}'

Then verify and manage it:

openclaw mcp doctor ppee --probe     # connects, and lists what the server advertises
openclaw mcp status --verbose        # all servers and their state
openclaw mcp show ppee               # the stored entry
openclaw mcp unset ppee              # remove it

With Gateway hot reload enabled, a new or changed server is picked up on the next turn without a restart. If it doesn't appear, restart the Gateway. For stdio servers, look for the Gateway's debug output prefixed bundle-mcp:ppee:, and check that the command resolves in the Gateway's environment.

Limit what the agent can call. OpenClaw can filter a server's tools, which suits PPEE well: expose only the read-only analysis tools.

openclaw mcp tools ppee --include 'analyze_pe,get_hashes,list_imports,list_exports,check_signature,get_strings'

or in the entry: toolFilter: { include: ["analyze_pe", "get_*", "list_*", "check_signature"] }. (patch_pe only exists when you start PPEE with --mcp-allow-write, so leaving that flag off is the first safeguard; see the security model.)

Official guides: Connect MCP servers · Manage saved MCP servers

Hermes Agent¶

Hermes Agent (Nous Research) reads MCP servers from mcp_servers in ~/.hermes/config.yaml, starts them when it starts, and registers each tool as mcp_<server>_<tool>: with the server named ppee, the assistant sees mcp_ppee_triage_pe, mcp_ppee_get_hashes and so on.

mcp_servers:
  ppee:
    command: "/opt/ppee/ppee-cli"
    args: ["--mcp"]

mcp_servers:
  ppee:
    command: "docker"
    args: ["run", "--rm", "-i", "--network", "none", "-v", "/home/me/samples:/samples:ro", "ppee-cli", "--mcp"]

Then check the connection, and load the change into a running session:

hermes mcp test ppee     # connects and lists the tools

In a Hermes session, /reload-mcp reloads the servers without a restart.

Limit what the agent can call. Hermes filters a server's tools under tools, so you can expose only the analysis tools you want:

mcp_servers:
  ppee:
    command: "/opt/ppee/ppee-cli"
    args: ["--mcp"]
    tools:
      include: ["triage_pe", "analyze_pe", "get_*", "list_*", "check_signature"]

(patch_pe only exists when you start PPEE with --mcp-allow-write, so leaving that flag off is the first safeguard; see the security model.)

Official guide: MCP in Hermes Agent

JetBrains AI Assistant¶

1. Open Settings → Tools → AI Assistant → Model Context Protocol (MCP) and click Add.
2. Choose STDIO as the transport.

3. Paste the JSON configuration:

   {
     "mcpServers": {
       "ppee": {
         "command": "C:\\Tools\\ppee\\ppee-cli.exe",
         "args": ["--mcp"]
       }
     }
   }
   

4. Set the server level: Global (all projects) or Project. Leave Working directory empty unless you use relative paths.

5. Click OK, then Apply. Applying starts the server; its status shows in the same list.

Official guide: MCP in JetBrains AI Assistant

Other clients¶

Any client that can launch a local stdio MCP server works. What you always provide is the same two things:

Look for a JSON key named mcpServers or servers (or context_servers, or a TOML [mcp_servers.*] table). The rest of this page applies unchanged.

Docker¶

Running the server in a container isolates it completely. In any config above, replace the command and arguments with:

"command": "docker",
"args": ["run", "--rm", "-i", "--network", "none",
         "-v", "C:/Samples:/samples:ro",
         "ppee-cli", "--mcp"]

Tell the assistant to use container paths (/samples/x.exe). Build the image first (see Docker); its name here is ppee-cli.

Enabling the write tool¶

Add --mcp-allow-write to the arguments to expose patch_pe:

"args": ["--mcp", "--mcp-allow-write"]

Read the security model first, and do not auto-approve this tool in any client (Cline's autoApprove, Gemini CLI's trust, or an "always allow" choice in an approval prompt).

First prompts to try¶

Once the tools appear, start with one of these (adjust the path):

• "Use ppee to triage C:\Samples\invoice.exe." (runs triage_pe: a ranked list of what looks unusual)
• "Use ppee to get the hashes of C:\Samples\invoice.exe."
• "Is setup.exe signed, and was it modified after signing?"
• "List the imports of agent.dll and group them by capability."
• "What was agent.dll built with, and does its metadata reveal any configuration?" (uses runtime analysis)

More ideas: tool reference → example prompts.

Testing without an AI tool¶

npx @modelcontextprotocol/inspector /opt/ppee/ppee-cli --mcp

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_hashes","arguments":{"path":"/samples/x.exe"}}}' \
  | ppee-cli --mcp

Troubleshooting¶

Next: Tool reference → · Security model →