Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / mcp-integration

MCP integration

Model Context Protocol (MCP) integration lets a Strix scan reach tools from user-configured local or remote servers. The CLI selects server definitions for a run, the scan owns a per-run registry of those connections, and agents discover and call the tools through a small shared interface.

Configuration contract

An MCP connection configuration describes one server and the name that identifies it during a run. The contract supports streamable HTTP endpoints and local servers started over standard input and output (stdio). HTTP connections can use bearer-token auth. A connection can also carry notes for the agent, an allowlist that limits which server tools are exposed, and a smaller set of active tools that search ranks first (strix/…/config.py• L30-72).

The transport determines the required access fields:

TransportAccess informationAgent-visible scope
httpurl, with optional bearer authAll listed tools unless allowed_tools limits them
stdiocommand, optional args and envAll listed tools unless allowed_tools limits them

Connection settings also control HTTP and stream read timeouts, MCP operation timeouts, and the limit for concurrent calls on a connection. These settings change how the connection runs without changing its tool names or allowlist (strix/…/config.py• L74-92).

Each connection name must be non-empty and unique in the run. The name is both the registry key and the stable handle that the agent passes to the MCP dispatch tools. The file loader keeps the first entry when duplicate names occur, while direct registry registration uses the latest entry for that name (strix/…/config.py• L30-40, strix/…/loader.py• L47-66, strix/…/registry.py• L332-343).

References: strix/…/config.py• L30-92 strix/…/loader.py• L47-66 strix/…/registry.py• L332-343

CLI selection

The CLI accepts an optional MCP server file and per-run connection selection. The parser turns these flags into loader settings before scan execution. --mcp-config must point to an existing file and overrides the default path; --mcp-server includes only the named connections; --mcp-exclude removes named connections (strix/…/cli_args.py• L223-245, strix/…/cli_args.py• L292-307).

The loader reads the selected file as a JSON list. It checks each entry against the connection contract. It skips invalid entries, removes duplicate names, and then applies the include and exclude filters. A missing file, unreadable file, invalid JSON, or non-list value gives the run an empty MCP set. The run therefore continues without MCP access when the file is not usable (strix/…/loader.py• L101-133).

References: strix/…/cli_args.py• L223-245 strix/…/cli_args.py• L292-307 strix/…/loader.py• L101-133

Scan attachment

The scan runner creates one registry for the run and attaches the selected connections before it builds the agents. The command-line path loads the user's file and wraps each configuration in a connection request. Other callers can provide requests directly, which lets managed integrations use the same attach and cleanup path without handing live sessions to the runner (strix/…/runner.py• L182-217, strix/…/runner.py• L378-410).

The attachment flow turns valid requests into supervised sessions and records only connections that finish their initial connection and tool listing. A connection that cannot connect is logged and skipped. If at least one connection is ready, the runner adds a short inventory to the scan prompt context. The inventory gives each connection a name, purpose, and tool count. The registry also supports inert registration for connections that should connect on first use. A scan with no ready or configured connections continues without MCP prompt context (strix/…/runner.py• L411-457, strix/…/client.py• L283-343, strix/…/registry.py• L319-381).

The registry is shared by the root agent and its child agents. This gives all agents the same connection names, cached tool catalogs, connection state, and live sessions instead of creating a separate MCP view for each agent (strix/…/registry.py• L12-15, strix/…/registry.py• L319-325).

This diagram shows how a CLI selection becomes a per-run agent capability.

flowchart LR
    A[CLI flags or default file] --> B[Load and validate configurations]
    B --> C[Apply include and exclude selection]
    C --> D[Register or attach connection requests]
    D --> E[Per-run MCP registry]
    E --> F[Shared agent discovery and dispatch tools]
    F --> G[Local or remote MCP server]

References: strix/…/runner.py• L378-457 strix/…/client.py• L283-379 strix/…/registry.py• L319-381

Connection names

The registry maps each configured name to its connection session and run metadata. This keeps server identity separate from the tool name reported by the server. The same name is used in the prompt inventory, in agent requests, in connection state, and in call attribution (strix/…/registry.py• L79-150, strix/…/registry.py• L258-317).

The connection-tool label is formed as <connection>_<tool> when a call needs a stable name for model or event handling. Characters outside letters, digits, underscores, and hyphens are replaced in this label so provider tool schemas accept it. The agent still passes the server's original tool name to call_mcp, and that name remains unchanged for the actual MCP call (strix/…/naming.py• L13-29, strix/…/agent_tools.py• L281-296).

The registry tracks a connection through states such as configured, connecting, connected, catalog loading, catalog ready, and unavailable. These states describe the connection's shared lifecycle and are visible to discovery and status consumers (strix/…/registry.py• L68-75, strix/…/registry.py• L203-240, strix/…/registry.py• L391-420).

References: strix/…/registry.py• L68-150 strix/…/registry.py• L203-240 strix/…/registry.py• L258-317 strix/…/registry.py• L391-420 strix/…/naming.py• L13-29 strix/…/agent_tools.py• L281-296

Agent tool access

Every root and child agent receives the same generic MCP tools. They keep the initial model tool set small: the agent first finds a connection, searches that connection's catalog, fetches one selected tool schema, and then sends a call with the server's own tool name and arguments (strix/…/factory.py• L560-598, strix/…/factory.py• L684-714).

The agent-facing sequence is:

  1. list_mcps returns connection ids, descriptions, tool counts, current state, and dead status. It does not return tool schemas.
  2. search_mcp_tools searches one connection by name and description. It returns a small ranked set and marks whether each result is in the connection's active tool set.
  3. get_mcp_tool_schema returns the exact input schema for one selected tool.
  4. call_mcp accepts the connection id, the server tool name, and an argument object. It validates the connection and tool, then dispatches the call through the live session.

describe_mcp remains a compatibility fallback that returns a full catalog when targeted search cannot identify a tool. Search and schema lookup load a connection's catalog on first use and share that catalog across agents (strix/…/agent_tools.py• L62-118, strix/…/agent_tools.py• L146-233, strix/…/registry.py• L203-240).

The allowed_tools setting is enforced when the server lists its tools. As a result, discovery and calling see the same restricted set. The active_tools setting does not widen that set; it only marks scan-relevant tools for search ranking. The registry also preserves optional provider labels and result transforms for managed connections. The CLI path leaves those values unset (strix/…/client.py• L123-182, strix/…/client.py• L269-280, strix/…/client.py• L346-379, strix/…/agent_tools.py• L176-196).

MCP tool errors are returned as failed tool results instead of being raised into the agent loop. This gives the run interfaces a stable failure marker while preserving the server's error content for the agent (strix/…/client.py• L213-267, strix/…/session.py• L361-396).

References: strix/…/factory.py• L560-598 strix/…/factory.py• L684-714 strix/…/agent_tools.py• L62-118 strix/…/agent_tools.py• L146-296 strix/…/client.py• L123-182 strix/…/client.py• L213-280 strix/…/registry.py• L203-240

Session lifecycle

Each MCP connection runs inside a supervised session. A dedicated task owns connection setup, the open transport, tool calls, and cleanup. Agent calls cross into that task through a queue, so a transport failure stays with its connection instead of cancelling the scan or another MCP connection (strix/…/session.py• L141-177, strix/…/session.py• L287-345, strix/…/session.py• L426-489).

The registry shares one connection task and one catalog task for each connection. A cold connection can therefore be opened once when several agents request it at the same time. When a session becomes unavailable, the registry clears its cached catalog and allows a later request to reconnect after the retry delay (strix/…/registry.py• L79-110, strix/…/registry.py• L145-240).

The session treats a failed connection as disposable and rebuilds it before a later attempt. Transient failures use bounded retries and backoff. Repeated failures place the connection in a temporary unavailable period. Repeated quarantine retires it. Authentication failures retire it at once. A permission or protocol rejection of one tool call returns a failed tool result while the connection remains usable (strix/…/session.py• L493-620, strix/…/session.py• L632-689). Calls are also limited by the connection's configured concurrency setting so one server does not receive unbounded parallel work (strix/…/session.py• L536-573).

The integration classifies failures without retaining request data that could contain secrets. It distinguishes authentication, permission, rate-limit, server, transport, timeout, protocol, and unknown failures. HTTP status and retry hints guide the retry or retirement decision (strix/…/failures.py• L16-29, strix/…/failures.py• L33-47, strix/…/failures.py• L65-150).

The runner closes all attached sessions during scan teardown. Normal shutdown uses the owning task so transport cleanup runs in the same task as setup. If startup is cancelled or shutdown cannot drain a pending operation, the session is cancelled and pending requests resolve as unavailable (strix/…/session.py• L300-345, strix/…/runner.py• L640-657, strix/…/client.py• L299-343).

References: strix/…/session.py• L141-177 strix/…/session.py• L287-345 strix/…/session.py• L361-396 strix/…/session.py• L426-489 strix/…/session.py• L493-689 strix/…/failures.py• L16-150 strix/…/registry.py• L79-110 strix/…/registry.py• L145-240 strix/…/runner.py• L640-657 strix/…/client.py• L299-343

Connection status

The integration exposes a non-secret connection roster to the terminal interface and the run viewer. The roster contains the name, optional provider label, tool count, state, and dead status. It never includes the endpoint, auth token, or full connection configuration (strix/…/runner.py• L81-131, strix/…/registry.py• L258-287, strix/…/registry.py• L404-420).

The runner sends the roster when connections become ready and again when a session becomes dead. It persists the same snapshot for the viewer and can send it to an attached interface sink for live display. Tool-call events separately carry the connection and underlying tool names. The transcript can then identify where a call went (strix/…/runner.py• L431-455, strix/…/state.py• L433-459, strix/…/live_view.py• L31-46, strix/…/registry.py• L428-432).

References: strix/…/runner.py• L81-131 strix/…/runner.py• L431-455 strix/…/state.py• L433-459 strix/…/live_view.py• L31-46 strix/…/registry.py• L258-287 strix/…/registry.py• L404-432

MCP is one part of the scan execution environment. See Configuration and external integrations for the wider settings model. See Configuration and provider settings for model and provider controls. See Proxy and Caido integration for the separate proxy and Caido boundary.

References: strix/…/runner.py• L378-459 strix/…/cli_args.py• L217-245

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the connection fields accepted by McpConnectionConfig, the JSON loader, and the CLI path aligned. A field that parses but is not selected or passed into the runner silently has no effect.
  • Preserve connection-name uniqueness across file loading, registry lookup, prompt inventory, and dispatch attribution. A name collision can change which server an agent reaches.
  • Keep the allowed_tools gate consistent with catalog counts, search results, schemas, and runtime calls. Keep active_tools as a ranking hint so it does not accidentally expose a tool outside the allowlist.
  • Keep the four generic agent tool names and their argument contracts aligned with MCP_DISPATCH_TOOLS and call attribution. A mismatch can make a valid dispatch invisible to the viewer or tracer.
  • Keep failure categories and the top-level success: false result marker aligned with the terminal and viewer consumers. A new result shape can make a failed MCP call look successful.
  • Update both the in-memory status sink and persisted run status when the roster shape changes. The TUI and viewer do not receive health from the same source.
  • Keep session cleanup on the session-owning task. Moving connection setup or teardown outside that lifecycle can let transport cancellation reach the scan or leak a local server process.

Important failure modes

TriggerConsequenceGuard
--mcp-config names a missing fileCLI argument parsing stops before the scan startsThe CLI checks that the path is a file and reports the flag error (strix/…/cli_args.py• L295-301)
A config file is missing, unreadable, malformed, or not a JSON listThe scan runs without MCP connectionsThe loader logs the problem and returns an empty list (strix/…/loader.py• L111-123)
One server entry fails validationThat entry is skipped while valid entries remain eligibleThe loader validates entries independently (strix/…/loader.py• L125-133)
A connection fails initial setup or first tool listingThat connection is omitted from eager attachment; a registered cold connection reports unavailable until a later retryAttachment is fail-open, and registry connection and catalog tasks contain the failure (strix/…/client.py• L283-343, strix/…/registry.py• L152-240)
A live session has a transient failure during a call or while idleThe session retries or enters a cooldown. Repeated cooldowns can retire the connectionFailure classification and bounded session recovery contain the failure (strix/…/failures.py• L119-150, strix/…/session.py• L493-689)
A provider rejects one call for permission or protocol reasonsThe agent receives a failed tool result while the connection stays usableThe session treats call rejection as request failure rather than connection death (strix/…/session.py• L600-620, strix/…/session.py• L719-742)
The agent uses an unknown connection or toolThe dispatch tool returns a corrective error instead of making a server callDispatch resolves the registry entry, loads the catalog, and validates the current tool list (strix/…/agent_tools.py• L164-233, strix/…/agent_tools.py• L258-296)
Several agents request the same cold connection or catalog at onceDuplicate setup or listing could waste resources or create inconsistent viewsThe registry shares one connection task and one catalog task per entry (strix/…/registry.py• L152-224)

Key files

FileWhy to read it
strix/…/cli_args.pyShows how MCP file and per-run selection flags enter the CLI flow.
strix/…/config.pyDefines the server access contract, transport rules, active and allowed tool sets, timeouts, and call limit.
strix/…/loader.pyExplains file selection, validation, duplicate handling, and fail-open loading.
strix/…/runner.pyConnects MCP configuration to the scan, prompt context, status reporting, and teardown.
strix/…/client.pyShows how transport connections are built, filtered, serialized, attached, and safely cleaned up.
strix/…/failures.pyDefines the non-secret failure classes that guide recovery and status messages.
strix/…/registry.pyDefines the per-run connection map, lazy catalog and connection sharing, lifecycle states, and metadata shared with agents and interfaces.
strix/…/agent_tools.pyDefines agent discovery, targeted tool search, schema lookup, compatibility catalog access, and call dispatch.
strix/…/session.pyExplains connection supervision, recovery, failure containment, concurrency, and cleanup.
strix/…/factory.pyShows why every root and child agent receives the generic MCP tools.
strix/…/state.pyShows which non-secret MCP connection data is persisted for run viewing.