Exposing Sidekick as an MCP Server¶

Beta

The Sidekick MCP server is a beta feature. Its tool surface, arguments, and response shape may change as we collect feedback.

The Sidekick plugin ships a Model Context Protocol (MCP) server that exposes Sidekick's workspaces and service-backed chat agent to outside MCP clients. With this turned on, an external AI agent (Claude Code, Cursor, a custom client, or any program that speaks MCP stdio) can:

List and rehydrate persisted Sidekick workspaces
Open binaries or BNDBs into a workspace
Send messages to the Sidekick agent and read back responses (including tool-call evidence from prior conversations)
Inspect chat state and transcripts

This is the inverse of Adding External Tools with MCP: that feature lets Sidekick consume MCP tools from outside; this feature lets outside agents call Sidekick as a tool.

Prerequisites¶

The Sidekick plugin is installed via Binary Ninja's plugin manager.
The plugin's pip dependencies — including mcp — are present in Binary Ninja's Python (the plugin manager installs these on plugin install).
BN_USER_DIRECTORY is set, points at a Binary Ninja user directory containing license.dat, and that user directory's settings configure a reachable Sidekick service (sidekick.service.host, sidekick.service.port, and the API key). See Settings.
An MCP client (such as the claude CLI) to drive the server.

How it works¶

The MCP server is a separate process that the MCP client launches on demand. It is not part of the running Binary Ninja application. When the client starts:

The client spawns the bundled launcher script with Binary Ninja's Python.
The launcher imports sidekick.mcp_server from the installed plugin and starts the MCP stdio loop.
Each MCP tool call runs synchronously against a Sidekick session, hitting the configured Sidekick service for any LLM-backed work.

Because the server runs outside the Binary Ninja GUI, all operations are headless. Binary Ninja itself does not need to be open while the MCP server is in use.

Registering the server¶

The bundled launcher lives inside the installed plugin at:

<BN_USER_DIRECTORY>/plugins/Vector35_Sidekick/sidekick/mcp_server/launch.py

Register it with your MCP client using Binary Ninja's bundled Python interpreter.

Claude Code (CLI)¶

claude mcp add sidekick \
  -e BN_USER_DIRECTORY=/path/to/binja/user/dir \
  -- /path/to/binja/python \
     /path/to/Vector35_Sidekick/sidekick/mcp_server/launch.py

After registration, restart your Claude Code session so the new server is attached. The sidekick_* tools will appear in the tool list.

Generic stdio JSON¶

For MCP clients that take a JSON config:

{
  "mcpServers": {
    "sidekick": {
      "command": "/path/to/binja/python",
      "args": [
        "/path/to/Vector35_Sidekick/sidekick/mcp_server/launch.py"
      ],
      "env": {
        "BN_USER_DIRECTORY": "/path/to/binja/user/dir"
      }
    }
  }
}

Locating Binary Ninja's Python¶

Binary Ninja's bundled Python interpreter is not the system python3. Use the interpreter that ships with your Binary Ninja installation, or any Python where import binaryninja succeeds. If import binaryninja fails, the launcher exits with a clear error message; see Troubleshooting.

Autonomous tool policy¶

The MCP transport has no human-in-the-loop. Tool calls issued by the Sidekick agent default to tool_policy="autonomous" when invoked through the MCP server, so the agent can run tools without prompting for per-call approval. The driving agent (your MCP client) is responsible for gating actions before forwarding them to Sidekick.

To run with a stricter policy, pass tool_policy="default" (or "inherit") to sidekick_create_chat or sidekick_call_agent. Note that without an approval channel — none is exposed over MCP — the chat will stall at the first tool call.

Available tools¶

Tool	Purpose
`sidekick_list_workspaces`	Discover persisted workspaces to resume prior analysis.
`sidekick_open_workspace`	Rehydrate a known workspace and (optionally) focus a specific BinaryView. Returns the loaded targets and their `binary_view_id` values.
`sidekick_open_targets`	Open one or more binaries or BNDBs into a workspace.
`sidekick_list_targets`	List open BinaryViews and their stable `binary_view_id` values.
`sidekick_list_chats`	Find prior conversations in a workspace.
`sidekick_create_chat`	Start a new Sidekick agent conversation. Defaults to autonomous policy.
`sidekick_call_agent`	Primary entry point: send a message to a Sidekick chat and return the assistant response. Creates the chat on demand by default.
`sidekick_get_history`	Retrieve transcript context, optionally including tool calls (set `include_tool_calls=true`).
`sidekick_get_status`	Inspect chat execution state (idle, running, errored, waiting for approval).
`sidekick_close_workspace`	Release loaded resources without deleting persisted data.

No v1 tool deletes or purges workspace data.

Cross-chat memory¶

When a new chat is created in an existing workspace, Sidekick injects a <session-briefing> block as the first message in the transcript. The briefing summarises stable context, active focus, recent evidence, and open questions across prior chats — so a fresh chat in a workspace has automatic access to what previous chats discovered. The driving MCP agent receives this briefing as part of every sidekick_call_agent response, in the messages array at index: 0 with injected: true.

Troubleshooting¶

`Binary Ninja License not provided`¶

The Sidekick service rejected the request because Binary Ninja could not produce a license. Check:

BN_USER_DIRECTORY points at a directory that contains license.dat.
That license is valid (open Binary Ninja's UI against the same user directory and confirm it loads).

`No module named 'binaryninja'`¶

The launcher was invoked with a Python interpreter that does not have the binaryninja module on its path. Use Binary Ninja's bundled Python directly, or configure PYTHONPATH to include Binary Ninja's Resources/python directories.

Empty workspace list when workspaces exist¶

BN_USER_DIRECTORY is unset or points at a different user directory than the one holding your workspaces. The MCP server resolves its workspaces database relative to this directory.

`Timed out waiting for chat to settle`¶

The chat reached a state requiring tool approval — but the MCP transport does not expose an approval channel. Create the chat with tool_policy="autonomous" (the default for MCP), or drive it through Binary Ninja's UI.

Limitations¶

stdio only. HTTP/SSE transports for the Sidekick MCP server are not currently supported.
No remote BinaryView control. The MCP server can open binaries and run the Sidekick agent, but it does not expose direct read/write of BinaryView state. Work that requires modifying a BinaryView should go through the agent's tool calls.
One process per client. The server is spawned per MCP client connection; concurrent clients each get their own process and runtime.

For programmatic access from within Binary Ninja, use the Sidekick API directly instead.