cortex-mcp
An MCP (Model Context Protocol) server for Cortex - the observable analysis and active response engine by StrangeBee/TheHive Project.
Cortex automates the analysis of observables (IPs, URLs, hashes, domains, emails, files) using analyzers and can execute response actions via responders. This MCP server exposes Cortex's full analysis pipeline to LLMs, enabling AI-driven observable enrichment and automated response orchestration.
Features
- 12 MCP tools covering analyzers, jobs, responders, and bulk operations
- 2 MCP resources for browsing Cortex state
- 2 MCP prompts with guided investigation workflows
- Full TLP/PAP support for data classification
- Bulk analysis across all applicable analyzers with taxonomy aggregation
- Structured error handling with meaningful messages
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
Set these environment variables before running the server:
| Variable | Required | Default | Description |
|---|---|---|---|
CORTEX_URL | Yes | - | Cortex base URL (e.g., https://cortex.example.com:9001) |
CORTEX_API_KEY | Yes | - | API key for authentication |
CORTEX_VERIFY_SSL | No | true | Set to false to skip SSL verification |
Example .env file:
CORTEX_URL=https://cortex.example.com:9001
CORTEX_API_KEY=your-api-key-here
CORTEX_VERIFY_SSL=true
Usage
With Claude Desktop
Add to your Claude Desktop MCP configuration (claude_desktop_config.json):
{
"mcpServers": {
"cortex": {
"command": "node",
"args": ["/path/to/cortex-mcp/dist/index.js"],
"env": {
"CORTEX_URL": "https://cortex.example.com:9001",
"CORTEX_API_KEY": "your-api-key-here"
}
}
}
}
Standalone
export CORTEX_URL=https://cortex.example.com:9001
export CORTEX_API_KEY=your-api-key-here
npm start
Development
export CORTEX_URL=https://cortex.example.com:9001
export CORTEX_API_KEY=your-api-key-here
npm run dev
MCP Tools
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) |
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 |
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 |
Bulk Operations
| Tool | Description |
|---|---|
cortex_analyze_observable | Run ALL applicable analyzers and return aggregated results with taxonomy summary |
MCP Resources
| URI | Description |
|---|---|
cortex://analyzers | List of all enabled analyzers with capabilities |
cortex://jobs/recent | Last 50 analysis jobs |
MCP Prompts
| Prompt | Description |
|---|---|
analyze-observable | Guided workflow for analyzing an observable through Cortex |
investigate-ioc | Deep investigation workflow for a suspicious IOC |
Examples
Analyze an IP address
Use cortex_analyze_observable to check the IP 185.220.101.42
with dataType "ip", tlp 2, pap 2.
The server will submit the IP to all analyzers that support the ip data type (VirusTotal, AbuseIPDB, etc.), wait for results, and return an aggregated report with taxonomy counts:
{
"observable": { "dataType": "ip", "data": "185.220.101.42" },
"analyzersRun": 4,
"summary": {
"malicious": 2,
"suspicious": 1,
"info": 1,
"safe": 0
},
"results": [...]
}
Run a specific analyzer
Use cortex_run_analyzer_by_name with analyzerName "VirusTotal",
dataType "hash", data "44d88612fea8a8f36de82e1278abb02f"
Check job status
Use cortex_get_job with jobId "AWl2d8x1kDx6FO7wxPBn"
Execute a responder
Use cortex_run_responder with responderId "Mailer_1_0",
objectType "case_artifact", objectId "~123456"
Supported Data Types
| Type | Examples |
|---|---|
ip | 8.8.8.8, 2001:db8::1 |
domain | example.com |
url | https://malware.example.com/payload |
fqdn | mail.example.com |
hash | MD5, SHA1, SHA256 hashes |
mail | user@example.com |
filename | malware.exe |
registry | HKLM\Software\Malware |
regexp | Regular expression patterns |
other | Any other observable type |
Testing
npm test # Run all tests
npm run test:watch # Run in watch mode
npm run lint # Type check only
Project Structure
cortex-mcp/
src/
index.ts # MCP server entry point
config.ts # Environment config + validation
client.ts # Cortex REST API client
types.ts # Cortex API type definitions
resources.ts # MCP resources
prompts.ts # MCP prompts
tools/
analyzers.ts # Analyzer tools
jobs.ts # Job management tools
responders.ts # Responder tools
bulk.ts # Bulk operations
tests/
client.test.ts # API client unit tests
tools.test.ts # Tool handler unit tests
package.json
tsconfig.json
tsup.config.ts
vitest.config.ts
License
MIT