How do I install Huntress?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Huntress need an API key?

The publisher lists these environment variables: HUNTRESS_API_KEY, HUNTRESS_API_SECRET, MCP_TRANSPORT, AUTH_MODE, LOG_LEVEL.

What transport does Huntress use?

Huntress runs locally over stdio.

When was Huntress last checked?

Last checked 2026-11-11. MCP server for Huntress — accounts, organizations, agents, incidents, and reports.

Huntress MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

docker run -i --rm ghcr.io/wyre-ai/huntress-mcp:v1.2.24

Credentials from the publisher

HUNTRESS_API_KEY — Huntress API key (public identifier portion of the API credential)
HUNTRESS_API_SECRET — Huntress API secret
MCP_TRANSPORT — Transport mode for the server. Set to 'stdio' for local CLI use; the image defaults to 'http' for gateway hosting.
AUTH_MODE — Credential source: 'env' reads vars locally, 'gateway' expects header injection from the WYRE MCP Gateway.
LOG_LEVEL — Log verbosity: debug, info, warn, error

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1HUNTRESS_API_KEY=<secret> HUNTRESS_API_SECRET=<secret> MCP_TRANSPORT=<value> AUTH_MODE=<value> LOG_LEVEL=<value> claude mcp add io.github.wyre-ai-huntress-mcp -- docker run -i --rm ghcr.io/wyre-ai/huntress-mcp:v1.2.24

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.wyre-ai-huntress-mcp": {4      "command": "docker",5      "args": [6        "run",7        "-i",8        "--rm",9        "ghcr.io/wyre-ai/huntress-mcp:v1.2.24"10      ],11      "env": {12        "HUNTRESS_API_KEY": "<secret>",13        "HUNTRESS_API_SECRET": "<secret>",14        "MCP_TRANSPORT": "<value>",15        "AUTH_MODE": "<value>",16        "LOG_LEVEL": "<value>"17      }18    }19  }20}

claude_desktop_config.json

Local · ociPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Huntress MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with structured access to Huntress cybersecurity platform data and operations.

Note: This project is maintained by Wyre Technology.

Quick Start

Claude Desktop — download, open, done:

Download huntress-mcp.mcpb from the latest release
Open the file (double-click or drag into Claude Desktop)
Enter your Huntress credentials when prompted (API Key, API Secret)

No terminal, no JSON editing, no Node.js install required.

Claude Code (CLI):

claude mcp add huntress-mcp \
  -e HUNTRESS_API_KEY=your-api-key \
  -e HUNTRESS_API_SECRET=your-api-secret \
  -- npx -y github:WYRE-AI/huntress-mcp

See Installation for Docker and from-source methods.

Features

🔌 MCP Protocol Compliance: Full support for MCP resources and tools
🛡️ Comprehensive Security Coverage: Tools spanning agents, organizations, incidents, escalations, billing, signals, and users
🔍 Decision-Tree Navigation: Start with huntress_navigate to explore domains, then dynamically load domain-specific tools
📝 CRUD Operations: Create, read, update, delete operations for organizations, memberships, incidents, and more
🔒 Secure Authentication: HTTP Basic Auth with Huntress API credentials
🌐 Dual Transport: Supports both stdio (local) and HTTP Streamable (remote/Docker) transports
📦 MCPB Packaging: One-click installation via MCP Bundle for desktop clients
🐳 Docker Ready: Containerized deployment with HTTP transport and health checks
⚡ Rate Limiting: Built-in rate limiter respects Huntress API limits (60 req/min)
📊 Structured Logging: Comprehensive logging with configurable levels

Installation
Configuration
Usage
Domains
Docker Deployment
Development
Testing
Contributing
License

Installation

Option 1: MCPB Bundle (Claude Desktop)

The simplest method — no terminal, no JSON editing, no Node.js install required.

Download huntress-mcp.mcpb from the latest release
Open the file (double-click or drag into Claude Desktop)
Enter your Huntress credentials when prompted (API Key, API Secret)

For Claude Code (CLI), one command:

claude mcp add huntress-mcp \
  -e HUNTRESS_API_KEY=your-api-key \
  -e HUNTRESS_API_SECRET=your-api-secret \
  -- npx -y github:WYRE-AI/huntress-mcp

Option 2: Docker

The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the service-to-service secret. In gateway mode, Huntress credentials arrive on each request as headers; they are not read from the environment.

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/huntress-mcp:latest

Compose refuses to start when CONDUIT_S2S_SECRET is unset:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Option 3: From Source

git clone https://github.com/WYRE-AI/huntress-mcp.git
cd huntress-mcp
npm ci
npm run build

Configuration

Copy .env.example and set the variables below.

Variable	Required	Description
`HUNTRESS_API_KEY`	For stdio and `AUTH_MODE=env`	Huntress API public key
`HUNTRESS_API_SECRET`	For stdio and `AUTH_MODE=env`	Huntress API secret
`MCP_TRANSPORT`	No	`stdio` (default) or `http`
`AUTH_MODE`	No	`gateway` (Docker image and Compose default) or `env`. Gateway mode requires `X-Huntress-Api-Key` and `X-Huntress-Api-Secret` on each `/mcp` request and never falls back to `HUNTRESS_*`. `env` uses those variables only after S2S auth succeeds.
`CONDUIT_S2S_SECRET`	Yes for HTTP	Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder (`changeme`, `secret`, `replace-me`, `your-s2s-secret`, and the other example values). Compose will not start without it. Never commit a real value. Generate one with `openssl rand -hex 32`.
`MCP_ALLOW_INSECURE_DEV`	No	Set to exactly `1` only for local development to start HTTP without `CONDUIT_S2S_SECRET`. The process logs a warning, does not enforce `X-Gateway-S2S`, and listens on `127.0.0.1` only. A non-loopback `MCP_HTTP_HOST` (including `0.0.0.0`) is ignored and the override is logged. A known placeholder secret is still refused.
`MCP_HTTP_HOST`	No	Bind address when `CONDUIT_S2S_SECRET` is set. Defaults to `127.0.0.1` when unset. The container image sets `0.0.0.0`.
`MCP_HTTP_PORT`	No	HTTP port. Defaults to `8080`.
`LOG_LEVEL`	No	Log level (`debug`, `info`, `warn`, `error`). Defaults to .

/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S:

t=<unix seconds>,v1=<hex hmac-sha256>

v1 is HMAC-SHA256 over the exact message t=<unix seconds>, keyed with CONDUIT_S2S_SECRET, hex-encoded. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401. The secret is never written to logs.

import { createHmac } from 'node:crypto';

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.CONDUIT_S2S_SECRET).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

In AUTH_MODE=gateway, /mcp also requires X-Huntress-Api-Key and X-Huntress-Api-Secret. Those headers are the only credential source for that request. A request missing either header returns 401 and does not fall back to HUNTRESS_API_KEY / HUNTRESS_API_SECRET.

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-huntress-api-key': apiKey,
    'x-huntress-api-secret': apiSecret,
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

Domains

The server uses decision-tree navigation. Start with huntress_navigate to pick a domain:

Domain	Tools
accounts	Get account info, get current actor
agents	List agents, get agent by ID
organizations	List, get, create, update, delete organizations
incidents	Incident reports (list/get/resolve), remediations (list/get/approve/reject), escalations (list/get/resolve)
billing	Billing reports, summary reports
signals	List/get security signals
users	Membership CRUD (list/get/create/update/delete)

Docker Deployment

See docker-compose.yml for full configuration. The checked-in Compose service is gateway mode. It does not set HUNTRESS_API_KEY or HUNTRESS_API_SECRET and does not use env_file, so a project .env cannot inject static vendor credentials into the container. Compose still interpolates CONDUIT_S2S_SECRET from that file and will not start when it is unset. The port is published on 127.0.0.1.

cp .env.example .env
# Set CONDUIT_S2S_SECRET. Leave it empty in the example; never commit a real value.
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses HUNTRESS_API_KEY and HUNTRESS_API_SECRET. It is separate from the gateway Compose service:

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e HUNTRESS_API_KEY=your-key \
  -e HUNTRESS_API_SECRET=your-secret \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/huntress-mcp:latest

Local HTTP without a secret is development-only. It binds 127.0.0.1 only and logs a warning:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Development

npm ci
npm run build       # Build the project
npm run dev         # Watch mode
npm run test        # Run tests
npm run lint        # Type-check
npm run clean       # Remove dist/

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Testing

npm test            # Run test suite
npm run test:watch  # Watch mode

Contributing

See CONTRIBUTING.md for guidelines.

Huntress

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Huntress?

Does Huntress need an API key?

What transport does Huntress use?

When was Huntress last checked?

Documentation

Huntress MCP Server

Quick Start

Features

Table of Contents

Installation

Option 1: MCPB Bundle (Claude Desktop)

Option 2: Docker

Option 3: From Source

Configuration

HTTP authentication

Domains

Docker Deployment

Development

Testing

Contributing

License