OPTIX MCP Server

OPTIX MCP Server

A standalone Python/FastAPI server that implements the Model Context Protocol (MCP) for the OPTIX threat intelligence platform. It exposes 26 analyst-friendly tools that AI assistants and programmatic consumers can use to query threat feeds, search documents and indicators, manage watchlists, triage IOCs, generate detection rules, trigger AI research, and produce intelligence reports — without needing to understand OPTIX's internal REST API.

Requirements

• Python 3.11+
• An active OPTIX installation
• An OPTIX API key (create one in OPTIX Settings → API Keys)

Environment Variables

Create a .env file in the OPTIX MCP/ directory to set these, or export them as shell variables.

# Only needed if self-hosting OPTIX at a custom URL:
OPTIX_API_URL=https://your-optix-instance.example.com
MCP_PORT=8090

Running Locally

cd "OPTIX MCP"
cp .env.example .env          # then edit .env with your OPTIX_API_URL
pip install -r requirements.txt
python main.py

The server starts on http://0.0.0.0:8090 by default.

• Health check: GET http://localhost:8090/health
• MCP SSE endpoint: GET http://localhost:8090/mcp (requires X-API-Key header)

Authentication

Every request to the MCP endpoint must include your OPTIX API key in the X-API-Key header:

X-API-Key: optix_your_api_key_here

Unauthenticated requests receive a structured 401 response:

{
  "error": "Missing API key",
  "detail": "Provide your OPTIX API key in the X-API-Key request header.",
  "docs": "See README.md for instructions on obtaining an API key."
}

Connecting to Claude Desktop

Recommended — via Smithery (no local install required):

Add the following to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "optix": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@optixcybersecurity/optix-mcp",
        "--",
        "--api-key",
        "optix_your_api_key_here"
      ]
    }
  }
}

Alternative — self-hosted local server:

{
  "mcpServers": {
    "optix": {
      "command": "python",
      "args": ["/path/to/OPTIX MCP/stdio.py"],
      "env": {
        "OPTIX_API_KEY": "optix_your_api_key_here"
      }
    }
  }
}

Connecting to Cursor

Recommended — hosted endpoint (no local install required):

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "optix": {
      "url": "https://optixthreatintelligence.co.uk/mcp",
      "headers": {
        "X-API-Key": "optix_your_api_key_here"
      }
    }
  }
}

Alternative — local server:

{
  "mcpServers": {
    "optix": {
      "url": "http://localhost:8090/mcp",
      "headers": {
        "X-API-Key": "optix_your_api_key_here"
      }
    }
  }
}

Credit System

Several tools consume OPTIX credits. The server enforces a pre-flight credit check before making any upstream call: if the cached balance is known to be insufficient, it returns an error immediately without deducting or attempting the operation.

After every successful credit-consuming call the server re-fetches the credit balance so that get_account_status always reflects the current state.

Available Tools

Authentication: All tools authenticate via the X-API-Key header set in your MCP client configuration — there is no api_key tool parameter. The key is validated against the OPTIX backend on every request.

Tool Overview

get_threat_feed

Returns a paginated stream of curated, scored intelligence documents from all OPTIX sources.

When to use: "What are the latest critical threats?" / "Show me recent TLP:AMBER intelligence."

search_indicator

Searches OPTIX for a specific indicator of compromise (IOC) by value.

When to use: "Has OPTIX seen 185.220.101.45?" / "What do we know about this hash?"

report_incident ⚡ 40 credits

Submits a structured incident report to OPTIX and generates a tactical intelligence report.

When to use: An analyst has completed an investigation and wants to create a formal intelligence report.

get_entity

Fetches a named threat intelligence entity (threat actor, malware, campaign, CVE, technique) by name or ID.

When to use: "Tell me about APT28" / "What do we know about LockBit?"

get_account_status

Returns your current OPTIX credit balance, monthly allocation, usage, reset date, and account context.

When to use: Before any credit-consuming operation, or when the analyst asks "how many credits do I have?"

No parameters required.

get_document

Fetches a specific intelligence document by its numeric OPTIX ID.

When to use: When you have a document ID from another tool and need full metadata and summary.

search_documents

Full-text search across all OPTIX intelligence documents.

When to use: "Find documents about supply chain attacks" / "Show me Mandiant reports from this week."

list_intelligence_reports

Lists generated intelligence reports (tactical, strategic, operational, technical, RFI) stored in OPTIX.

When to use: "What intelligence reports have we produced?" / "Show me all RFI reports."

get_intelligence_report

Retrieves the full content of a specific intelligence report.

When to use: After list_intelligence_reports to fetch the full text of a report.

get_attack_matrix

Retrieves the OPTIX MITRE ATT&CK coverage matrix — which techniques have been observed in intelligence data and which have detection rules.

When to use: "What ATT&CK techniques are we seeing?" / "Do we have detection coverage for T1566?"

get_watchlist

Lists all entities on the analyst's OPTIX watchlist.

When to use: "What entities am I watching?" / "Show my watchlist."

No parameters required.

add_to_watchlist

Adds an entity to the analyst's watchlist to receive notifications when new intelligence mentions it.

When to use: "Start watching APT29" (get the entity ID first with get_entity).

remove_from_watchlist

Removes an entity from the analyst's watchlist.

When to use: "Stop watching LockBit."

get_headlines

Returns AI-synthesised threat intelligence headlines summarising the most active current threats.

When to use: "What's happening in the threat landscape right now?" / "Give me a briefing."

No parameters required.

get_threat_cards

Returns profile-matched situational awareness threat cards showing active threats with observed TTPs and targeted sectors.

When to use: "What threats are most relevant to us?" / "Show me the threat cards for the last 30 days."

get_ioc_context

Returns enriched community context for an IOC including analyst vote tallies, co-occurring threat actors and malware, ATT&CK techniques, and source documents.

When to use: "What do analysts think about this IP?" / "Is this domain confirmed malicious?"

get_coverage_gaps

Analyses an intelligence document to identify MITRE ATT&CK techniques it references and determines which lack detection coverage.

When to use: "Does our detection stack cover the techniques in this report?" / "What are our coverage gaps from this document?"

ai_search

Natural language or keyword search across OPTIX documents and entities with optional AI query expansion.

When to use: "Find everything about LockBit's recent TTPs" / "Search for Volt Typhoon."

research_entity ⚡ 15 credits

Triggers deep AI research on an entity — OPTIX crawls authoritative sources and enriches the entity's profile with structured intelligence.

When to use: "Do a deep dive on APT29" / "Research the latest on LockBit."

Supported entity types: ThreatActor, MalwareFamily, Vulnerability, Tool, Campaign, Technique.

ask_entity ⚡ 4 credits

Generates a SIEM threat hunting query for a specific entity using its known TTPs, IOCs, and intelligence history.

When to use: "Generate a KQL hunt for APT28" / "Write a Sigma rule to detect LockBit."

Supported entity types: ThreatActor, MalwareFamily, Tool, Vulnerability.

generate_detection_rule ⚡ 4 credits

Generates a SIEM detection rule for a specific MITRE ATT&CK technique.

When to use: "Write a Splunk detection for T1059.001" / "Create a KQL rule for PowerShell abuse."

generate_tradecraft_query ⚡ 4 credits

Generates a broad SIEM hunting query covering the complete known tradecraft of a threat actor or malware family.

When to use: "Generate a multi-technique hunt for APT29 in Sentinel" / "Write a comprehensive Sigma rule set for Volt Typhoon."

generate_report ⚡ 40 credits

Generates a strategic, operational, technical, or RFI intelligence report using OPTIX's document and entity corpus.

When to use: "Write a strategic report on the ransomware threat landscape" / "Generate an RFI on APT40."

submit_feedback

Submits a relevance vote (upvote or downvote) on an OPTIX intelligence document. Community votes improve OPTIX scoring and feed personalisation.

When to use: "Upvote this document — it's very relevant" / "Downvote this, it's not applicable to us."

save_feed_view

Saves a named feed filter configuration so the analyst can recall it later.

When to use: "Save this filter as 'Critical malware this week'" / "Bookmark my current view."

triage_ioc

Applies a triage verdict to one or more IOCs, recording analyst judgement about their disposition.

When to use: "Mark these IPs as confirmed malicious" / "Flag this domain as a false positive."

Health Endpoint

GET /health returns service status without requiring authentication:

{
  "status": "ok",
  "version": "1.0.0",
  "optix_connected": true,
  "optix_url": "https://your-optix-instance.example.com",
  "timestamp": "2024-04-19T12:00:00Z"
}

If optix_connected is false, status will be degraded and tool calls will fail until the OPTIX backend is reachable.

Error Handling

All tools return structured error messages rather than raising exceptions to the AI client: