MCP server

IVRE ships an MCP (Model Context Protocol) server that exposes the database to LLM agents. It is installed as the ivre mcp-server subcommand and communicates over stdio, so it is meant to be launched by an MCP-capable client (Claude Code, Claude Desktop, Cursor, OpenCode, …).

Once wired up, the LLM can answer questions like:

  • “How many hosts are running SSH?”

  • “Show me the top 10 products on port 443 in Germany.”

  • “Find all hosts in 192.168.1.0/24 with open port 80.”

  • “What operating systems are most common in AS13335?”

  • “List hosts affected by CVE-2021-44228.”

The server requires a configured, populated IVRE instance; it reads the regular ivre.conf like the rest of IVRE.

Installation

The server depends on the mcp Python package, which is declared as an optional dependency. Install IVRE with the [mcp] extra:

pip install 'ivre[mcp]'

The command can then be launched as:

ivre mcp-server

Without a connected client, the process starts and waits for MCP JSON-RPC messages on stdin/stdout. Stop it with Ctrl+C.

Data purposes

Every tool takes a purpose parameter that selects the data source:

Purpose

Description

view

Consolidated, deduplicated merge of nmap and passive

nmap

Active scan results (Nmap, Masscan, etc.)

passive

Passively collected network traffic data

Default to view. Use nmap or passive only when you need source-specific data or a tool is not available under view.

Tool reference

Filter builders

Filters are opaque tokens. Build them with these tools and combine them with flt_and / flt_or.

Tool

Filters by

searchnet

Network (CIDR) or host address

searchhost

Exact host address

searchhostname

Hostname (exact or regex)

searchdomain

Domain name

searchport

Open port (TCP/UDP)

searchservice

Detected service name

searchproduct

Detected product name

searchdevicetype

Device type

searchcountry

Country code (ISO 3166-1 alpha-2)

searchasnum

Autonomous System number or name

searchos

Detected operating system

searchscript

Nmap script name or output

searchcve

CVE identifier (matches “Vulnerable” tag info)

searchcategory

Category

searchtag

Tag value (and optionally tag info)

searchrecontype

Passive reconnaissance type

searchsensor

Passive sensor name

Filter combinators

Tool

Description

flt_and

Combine two filters with logical AND

flt_or

Combine two filters with logical OR

flt_empty

Return the empty filter (matches everything)

Query tools

Tool

Description

count

Count matching records

get

Retrieve matching records (paginated, sortable)

topvalues

Most frequent values of a field

distinct

Distinct values of a field

describe_schema

List available field paths for a given purpose

nmap_service_values

Known Nmap service / product values (discovery)

A resource at ivre://guides/scope-discovery is also exposed; the server’s top-level instructions point agents at it when they start exploring a scope.

HTTP transport

In addition to stdio, the server can be exposed over HTTP using the Model Context Protocol Streamable HTTP transport. This is how remote or shared MCP deployments are typically served.

Starting the HTTP transport

ivre mcp-server --http \
                --bind 127.0.0.1 \
                --port 9100 \
                --path /mcp

CLI flags:

Flag

Description

--http

Switch from stdio to Streamable HTTP.

--bind

Bind address. Default 127.0.0.1.

--port

TCP port. Default 9100.

--path

HTTP path prefix for the MCP endpoint. Default /mcp.

--allow-anonymous

Disable bearer-token auth. Required to bind a non-loopback address when the IVRE Web auth backend is not configured.

Defaults can also be set from ivre.conf via MCP_HTTP_BIND, MCP_HTTP_PORT, MCP_HTTP_PATH and MCP_HTTP_ALLOW_ANONYMOUS.

Authentication

The HTTP transport supports two authentication shapes against the same underlying Web Authentication user store. Both are bearer-token based; clients pick whichever fits the MCP integration they ship.

API-key bearer (always enabled)

MCP clients authenticate with Authorization: Bearer <api-key>; the server verifies the token against db.auth.validate_api_key (the same code path used by the Web UI) and refuses unauthenticated requests when WEB_AUTH_ENABLED is set.

To create an API key, log in to the Web UI as the user, open Admin > API Keys and click Create. Keep the key secret – revoking it from the Web UI immediately invalidates MCP clients carrying it.

Per-user access controls

Per-user access controls (WEB_INIT_QUERIES, WEB_DEFAULT_INIT_QUERY, group-based rules) are honoured for every MCP tool call, regardless of which authentication shape the client used: the authenticated user is resolved from the bearer token and the resulting init filter is AND-ed with any filter built by the client.

Safety defaults

  • When --bind is not a loopback address and authentication is not configured, ivre mcp-server --http refuses to start. Either bind to loopback, enable WEB_AUTH_ENABLED, or pass --allow-anonymous to acknowledge the risk.

  • Anonymous mode disables all access control. Use it only for single-user local development.

Reverse proxy (nginx)

For production deployments, terminate TLS in nginx and reverse-proxy to the MCP HTTP server. FastMCP registers the endpoint at exactly /mcp (no trailing slash), so use an exact-match location: a prefix location /mcp/ block would trigger nginx’s automatic trailing-slash 301 and Starlette’s /mcp/ -> /mcp redirect, producing a loop, and a regex location is incompatible with a proxy_pass URI part. The Streamable-HTTP transport relies on server-sent events, so disable response buffering and bump the read timeout:

location = /mcp {
    proxy_pass              http://127.0.0.1:9100/mcp;
    proxy_http_version      1.1;
    proxy_set_header        Host              $host;
    proxy_set_header        X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header        X-Forwarded-Proto $scheme;
    proxy_set_header        Authorization     $http_authorization;
    proxy_buffering         off;
    proxy_cache             off;
    proxy_read_timeout      1h;
    proxy_send_timeout      1h;
    chunked_transfer_encoding on;
}

The MCP server derives the externally-visible origin (used in WWW-Authenticate: Bearer ..., resource_metadata="..." and in the /.well-known/oauth-protected-resource/... JSON document) from each request’s Host: and X-Forwarded-Proto: headers, the same trust surface as the Web UI’s Referer: header check (see WEB_ALLOWED_REFERERS in Configuration). The snippet above forwards both correctly. The public path must match the upstream --path (both default to /mcp); rewriting via X-Forwarded-Prefix is not currently supported.

HTTP client configuration

Claude Desktop, Claude Code, Cursor, VS Code and Windsurf support connecting to remote MCP servers. Example Claude Code snippet for ~/.claude/settings.json or a project-level .mcp.json:

{
  "mcpServers": {
    "IVRE": {
      "type": "http",
      "url": "https://ivre.example.com/mcp",
      "headers": {
        "Authorization": "Bearer IVRE_API_KEY_HERE"
      }
    }
  }
}

The exact JSON schema differs slightly between clients; consult the client documentation for the precise key names.

Docker

The reference Docker deployment (see Docker) ships a dedicated ivre/web-mcp image that runs ivre mcp-server --http on port 9100 inside the Compose network. The ivre/web nginx container reverse-proxies it at /mcp, so no extra configuration is required to reach it from an MCP client at http(s)://<host>/mcp.

The image starts with --allow-anonymous because the MCP port is not published on the host. For any production use, enable the IVRE Web auth backend (WEB_AUTH_ENABLED = True in ivre.conf), create an API key from Admin > API Keys in the Web UI, and override the ivremcp command: in docker-compose.yml to drop --allow-anonymous.

Client setup

All snippets below assume ivre-mcp-server resolves to the console script installed by the [mcp] extra. If it is installed in a virtualenv that is not on the client’s PATH, use the absolute path to the executable, or wrap the invocation in an activation script.

Note

These snippets configure the ivre mcp-server subcommand. A convenience console-script entry for it is not installed; clients below all call ivre with mcp-server as the first argument.

OpenCode

Add to your workspace opencode.json (or global ~/.config/opencode/opencode.json):

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

Claude Code

Add to ~/.claude/settings.json or to a project-level .mcp.json:

{
  "mcpServers": {
    "IVRE": {
      "command": "ivre",
      "args": ["mcp-server"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (accessible via Settings > Developer > Edit Config):

{
  "mcpServers": {
    "IVRE": {
      "command": "ivre",
      "args": ["mcp-server"]
    }
  }
}

Cursor

Go to Settings > Tools & Integrations > New MCP Server, select “command” type, and enter ivre mcp-server. Alternatively, add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "IVRE": {
      "command": "ivre",
      "args": ["mcp-server"]
    }
  }
}

VS Code (GitHub Copilot)

Requires the GitHub Copilot Chat extension. Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "IVRE": {
      "type": "stdio",
      "command": "ivre",
      "args": ["mcp-server"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "IVRE": {
      "command": "ivre",
      "args": ["mcp-server"]
    }
  }
}

JetBrains IDEs

Requires IntelliJ IDEA 2025.1+ (or equivalent). Go to Settings > Tools > AI Assistant > MCP Servers, click +, and add:

{
  "mcpServers": {
    "IVRE": {
      "command": "ivre",
      "args": ["mcp-server"]
    }
  }
}

Extending the server

Third parties can add tools and resources via entry points in the ivre.plugins.mcp_server group. See MCP server plugins for the plugin author guide.