README.md
An MCP server for the Cortex observable analysis and active response engine.
cortex-mcp
An MCP (Model Context Protocol) server for Cortex by StrangeBee/TheHive Project. Cortex automates observable analysis (IPs, URLs, hashes, domains, emails, files) using analyzers and executes response actions via responders. This MCP server exposes Cortex's full analysis and administration pipeline to LLMs.
Features
- 31 MCP tools covering the complete Cortex API surface
- 4 MCP resources for browsing Cortex state
- 4 MCP prompts with guided workflows (setup, investigation, triage)
- Full analyzer/responder lifecycle: browse definitions, enable, configure, disable
- Auto-detection of observable data types (IP, domain, hash, URL, email)
- Bulk analysis across all applicable analyzers with taxonomy aggregation
- Job cleanup with dry-run support
- User API key management (create, renew, retrieve)
- Organization CRUD with status management
- Dual API key support: org-level operations + superadmin administration
Prerequisites
- Node.js 20 or later
- A running Cortex instance (v3.x recommended)
- A Cortex API key with appropriate permissions
Installation
git clone https://github.com/solomonneas/cortex-mcp.git
cd cortex-mcp
npm install
npm run build
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
CORTEX_URL |
Yes | - | Cortex base URL (e.g., http://cortex.example.com:9001) |
CORTEX_API_KEY |
Yes | - | API key for normal operations (org admin level) |
CORTEX_SUPERADMIN_KEY |
No | - | Superadmin API key for org/user/definition management |
CORTEX_VERIFY_SSL |
No | true |
Set to false to skip SSL verification |
CORTEX_TIMEOUT |
No | 30 |
Request timeout in seconds |
Usage
With Claude Desktop
{
"mcpServers": {
"cortex": {
"command": "node",
"args": ["/path/to/cortex-mcp/dist/index.js"],
"env": {
"CORTEX_URL": "http://cortex.example.com:9001",
"CORTEX_API_KEY": "your-org-admin-key",
"CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
}
}
}
}
OpenClaw
Add to your openclaw.json:
{
"mcp": {
"servers": {
"cortex": {
"type": "stdio",
"command": "node",
"args": ["/path/to/cortex-mcp/dist/index.js"],
"env": {
"CORTEX_URL": "http://your-cortex:9001",
"CORTEX_API_KEY": "your-api-key"
}
}
}
}
}
Standalone
export CORTEX_URL=http://cortex.example.com:9001
export CORTEX_API_KEY=your-org-admin-key
npm start
MCP Tools (31)
Status
| Tool | Description |
|---|---|
cortex_get_status |
Get Cortex instance health, version, and configuration |
Analyzer Tools
| Tool | Description |
|---|---|
cortex_list_analyzers |
List all enabled analyzers, optionally filtered by data type |
cortex_get_analyzer |
Get details about a specific analyzer by ID |
cortex_run_analyzer |
Submit an observable to a specific analyzer for analysis |
cortex_run_analyzer_by_name |
Run an analyzer by name instead of ID (convenience wrapper) |
cortex_run_analyzer_file |
Submit a file (from path or base64) to an analyzer for analysis |
Analyzer Definition Tools
| Tool | Description |
|---|---|
cortex_list_analyzer_definitions |
Browse all 260+ available analyzer definitions with filtering (by data type, free/no-config, search) |
cortex_enable_analyzer |
Enable an analyzer definition in the current org with configuration |
cortex_disable_analyzer |
Disable (remove) an enabled analyzer |
Job Tools
| Tool | Description |
|---|---|
cortex_get_job |
Get the status and details of an analysis job |
cortex_get_job_report |
Get the full report of a completed analysis job |
cortex_wait_and_get_report |
Wait for a job to complete and return the report |
cortex_list_jobs |
List recent analysis jobs with optional filters |
cortex_get_job_artifacts |
Get artifacts (extracted IOCs) from a completed job |
cortex_delete_job |
Delete a specific job |
cortex_cleanup_jobs |
Bulk delete jobs by status or age (with dry-run) |
Responder Tools
| Tool | Description |
|---|---|
cortex_list_responders |
List all enabled responders, optionally filtered by data type |
cortex_run_responder |
Execute a responder action against a TheHive entity |
Responder Definition Tools
| Tool | Description |
|---|---|
cortex_list_responder_definitions |
Browse all 137+ avai |
Tools (5)
cortex_get_statusGet Cortex instance health, version, and configurationcortex_run_analyzerSubmit an observable to a specific analyzer for analysiscortex_get_job_reportGet the full report of a completed analysis jobcortex_run_responderExecute a responder action against a TheHive entitycortex_cleanup_jobsBulk delete jobs by status or age with dry-run supportEnvironment Variables
CORTEX_URLrequiredCortex base URLCORTEX_API_KEYrequiredAPI key for normal operationsCORTEX_SUPERADMIN_KEYSuperadmin API key for administrationCORTEX_VERIFY_SSLSet to false to skip SSL verificationCORTEX_TIMEOUTRequest timeout in secondsConfiguration
claude_desktop_config.json
{"mcpServers": {"cortex": {"command": "node", "args": ["/path/to/cortex-mcp/dist/index.js"], "env": {"CORTEX_URL": "http://cortex.example.com:9001", "CORTEX_API_KEY": "your-org-admin-key", "CORTEX_SUPERADMIN_KEY": "your-superadmin-key"}}}}Try it
→Check the health status of my Cortex instance.
→Run an analysis on the IP address 1.1.1.1 using all available analyzers.
→Get the report for the last completed analysis job.
→List all enabled responders currently available in Cortex.
→Clean up all jobs older than 30 days using a dry-run first.