> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwno.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Stateful debugging, exploit I/O, and workspace automation for autonomous pwn workflows over MCP.

<img className="block dark:hidden" src="https://mintcdn.com/pwno/sGXcKXJ8po4-pnQ3/images/banner-light.png?fit=max&auto=format&n=sGXcKXJ8po4-pnQ3&q=85&s=e6c2f2ab825187088d4dc663fcbf2366" alt="pwno-mcp banner" width="2220" height="400" data-path="images/banner-light.png" />

<img className="hidden dark:block" src="https://mintcdn.com/pwno/sGXcKXJ8po4-pnQ3/images/banner-dark.png?fit=max&auto=format&n=sGXcKXJ8po4-pnQ3&q=85&s=aee03739943391449270f5c6ab020729" alt="pwno-mcp banner" width="2220" height="400" data-path="images/banner-dark.png" />

`pwno-mcp` runs GDB + pwndbg in an isolated environment and exposes session-aware debugging, exploit-driver I/O, and helper tooling over MCP for agentic clients.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Launch the server with Docker and connect your MCP client.
  </Card>

  <Card title="Choose a client" icon="plug" href="/client-setup/index">
    Pick Claude, Cursor, OpenCode, or Codex CLI and copy a working config.
  </Card>

  <Card title="Guides" icon="bug" href="/guides/index">
    Follow task-oriented walkthroughs for first-run debugging, attach flows, exploit I/O, and multi-session work.
  </Card>

  <Card title="Reference" icon="square-terminal" href="/tool-reference/index">
    Jump straight to debugger, automation, and attach API details.
  </Card>
</CardGroup>

## Why it exists

The project is built for LLM-driven binary research workflows where a stateless shell is not enough. It keeps debugger state alive across calls, supports multiple parallel sessions, and pairs low-level debugging with helper tools for process management, Python execution, repo fetching, and exploit-driver flows.

You can use `pwno-mcp` to participate in CTFs, research, and exploit development workflows.

You can read the background story [here](/background-story).

## Typical workflow

<Steps>
  <Step title="Launch pwno-mcp">
    Use the Docker flow in [Quick Start](/quickstart). Most users start with HTTP transport and the default `http://127.0.0.1:5500/mcp` endpoint.
  </Step>

  <Step title="Connect your client">
    Pick a page under [Client Setup](/client-setup/index) and add the server using either HTTP or stdio.
  </Step>

  <Step title="Create a debug session">
    Start with `create_debug_session`, then `set_file`, `set_breakpoint`, and `run`. The walkthrough in [First Debug Session](/guides/first-debug-session) shows the full sequence.
  </Step>

  <Step title="Automate deeper workflows">
    Move on to [Guides](/guides/index) and the [Reference](/tool-reference/index) section when you need attach flows, exploit I/O, or workspace automation.
  </Step>
</Steps>

<Info>
  Paths passed to tools should normally resolve inside `/workspace`. If you mount `./workspace` from your host into the container, a host file like `./workspace/chal` becomes `/workspace/chal` in tool calls.
</Info>

## Runtime model

* The default HTTP endpoint is `http://127.0.0.1:5500/mcp`.
* The health endpoint is `http://127.0.0.1:5500/healthz`.
* The local attach helper API runs on `http://127.0.0.1:5501/attach` in HTTP mode by default.
* Most file paths passed to tools should resolve inside `/workspace`.
* Multi-session workflows should pass explicit `session_id` values.

## About

This project is maintained by [Pwno](https://pwno.io), an AI cybersecurity startup founded by [Ruikai](https://ruik.ai) and [Evan Luo](https://evannotfound.com).