> For the complete documentation index, see [llms.txt](https://docs.hex-rays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/how-tos/use-with-coding-agents.md).

# Use IDA Pro Headless with coding agents

IDA Pro Headless is made for AI agents working alongside your analysts. There are two ways to give an agent access to IDA:

* **Let the agent write idalib scripts**, guided by the `AGENTS.md` file of the package.
* **Give the agent IDA as tools**, through the [IDA MCP Server](https://docs.hex-rays.com/add-ons/mcp/overview.md).

Both use headless seats: each database the agent opens takes a seat, and closing it gives the seat back.

## Prerequisites

* IDA Pro Headless installed and checked, as in [Getting Started](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/getting-started.md): the license agreement accepted, the `idapro` module installed, and `IDADIR` and `IDA_LICENSE` set.
* A coding agent, such as Claude Code, Codex or Cursor.

## Option 1: Let the agent write idalib scripts

`AGENTS.md`, at the top of every package, tells a coding agent what it needs to work with IDA Pro Headless:

* how to set up the environment,
* how to use the idalib API, with a minimal script,
* how to take and name seats, and what to do when no seat is free,
* the rules that matter.

Point your agent at the package folder and ask it to read `AGENTS.md` first:

> Read AGENTS.md in \~/ida-pro-headless-9.5-x64linux, then list the functions of \~/work/sample that call recv.

### Rules for agents

The rules in `AGENTS.md` apply to any script, written by an agent or not:

* Import `idapro` first, before any other IDA module.
* Always close the database, so the seat goes back to the pool.
* Open one database per process.
* Work on a copy of the binary, not on the original.
* Keep one process per binary, and ask it several questions, rather than starting one process per question.

## Option 2: Give the agent IDA as tools with IDA MCP

The official [Hex-Rays IDA MCP Server](https://github.com/HexRaysSA/ida-mcp) works with IDA Pro Headless through idalib. It gives your agent tools such as `open_database`, `execute_python` and `close_database`, and runs IDAPython and [Domain API](https://docs.hex-rays.com/developer/domain-api.md) code for it.

{% hint style="info" icon="desktop-arrow-down" %}

### Quick install with HCLI

`uvx ida-hcli mcp install` installs IDA MCP and offers to configure the agent harnesses it supports (Claude, Codex, Copilot and others). Then make sure the agent starts IDA MCP with the `IDADIR` and `IDA_LICENSE` of your IDA Pro Headless installation, as below. See [IDA MCP: Getting Started](https://docs.hex-rays.com/add-ons/mcp/getting-started.md).
{% endhint %}

To configure it by hand, add IDA MCP to your agent's MCP configuration, with the environment of your IDA Pro Headless installation. The section **Use with AI agents (IDA MCP)** of the package `README.md` shows the exact configuration for your platform. A typical configuration looks like this:

```json
{
  "mcpServers": {
    "ida": {
      "command": "uvx",
      "args": ["ida-mcp", "stdio"],
      "env": {
        "IDADIR": "/home/analyst/ida-pro-headless-9.5-x64linux/ida-pro-headless-9.5",
        "IDA_LICENSE": "server:host=licsrv.example.com:port=65434:instance=mcp-agent"
      }
    }
  }
}
```

{% hint style="info" %}
`uvx` downloads IDA MCP and its dependencies from PyPI the first time it runs, so the agent's machine needs internet access for that. IDA Pro Headless itself works offline.
{% endhint %}

### Try it

Ask your agent to open a binary, answer a question about it, and close it:

> Open \~/work/sample in IDA, tell me how many functions it has and what the first three are called, then close it.

Behind the scenes, the agent calls the IDA MCP tools:

```
→ open_database {"path": "/home/analyst/work/sample"}
{"backend": "idalib", "status": "current", ...}

→ execute_python
funcs = list(db.functions)
print(len(funcs), 'functions in', db.module)
print('first:', ', '.join(db.functions.get_name(f) for f in funcs[:3]))

stdout:
506 functions in sample
first: .init_proc, sub_4020, sub_4030

→ close_database {}
{"closed": true, "final_lease": true, "idb_path": "/home/analyst/work/sample.i64"}
```

While the database is open, its seat shows on the **Allocations** page of the license server console, under the instance name `mcp-agent`.

## Run several agents at once

Each agent, and each database it opens, takes its own seat. To run several agents in parallel, give each one its own instance name and make sure your pool has enough headless seats. See [Headless seats](https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/concepts/headless-seats.md#how-many-seats-do-you-need).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hex-rays.com/editions-and-licenses/license-types/ida-pro-headless/how-tos/use-with-coding-agents.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
