Optix

OPTIX MCP 服务

一个独立的 Python/FastAPI 服务，为 OPTIX 威胁情报平台实现了 Model Context Protocol (MCP)。它提供 28 个便于分析师使用的工具，AI 助手和程序化使用者可借此查询威胁情报源、搜索文档和指标、管理监控列表、研判 IOC、生成检测规则、触发 AI 研究并生成情报报告，无需了解 OPTIX 的内部 REST API。

要求

• Python 3.11+
• 正在运行的 OPTIX 安装实例
• OPTIX API 密钥（在 OPTIX Settings → API Keys 中创建）

环境变量

变量	必填	默认值	说明
OPTIX_API_URL	否	https://optixthreatintelligence.co.uk	OPTIX 后端的基础 URL。仅在可自托管时覆盖。
MCP_HOST	否	0.0.0.0	MCP 服务绑定的主机地址
MCP_PORT	否	8090	MCP 服务监听的端口
OPTIX_REQUEST_TIMEOUT	否	30	上游 OPTIX 调用超时前等待的秒数
OPTIX_SKIP_AUTH	否	false	设为 true 时，跳过 API 密钥验证，允许未认证的工具列表查询（供 Glama 注册表检查使用）。切勿在生产环境中设为 true。

在 OPTIX MCP/ 目录中创建 .env 文件来设置这些变量，或将它们导出为 shell 变量。

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

本地运行

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

服务默认在 http://0.0.0.0:8090 上启动。

• 健康检查： GET http://localhost:8090/health
• MCP SSE 端点： GET http://localhost:8090/mcp（需要 X-API-Key 标头）

身份验证

每个发往 MCP 端点的请求都必须在 X-API-Key 标头中包含你的 OPTIX API 密钥：

X-API-Key: optix_your_api_key_here

未认证的请求会收到结构化的 401 响应：

{
  "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."
}

连接到 Claude Desktop

推荐 — 通过 Smithery（无需本地安装）：

将以下内容添加到 Claude Desktop 配置文件中：

• 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"
      ]
    }
  }
}

替代方案 — 可自托管的本地服务：

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

连接到 Cursor

推荐 — 托管端点（无需本地安装）：

添加到 ~/.cursor/mcp.json：

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

替代方案 — 本地服务：

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

---

积分系统

若干工具会消耗 OPTIX 积分。服务在进行任何上游调用前都会执行预先积分检查：如果已知缓存余额不足，会立即返回错误，不扣除积分，也不尝试执行操作。

每次成功调用消耗积分的工具后，服务都会重新获取积分余额，以确保 account.status 始终反映当前状态。

操作	费用
incident.report	40 积分
report.generate	40 积分
entity.research	15 积分
entity.ask	4 积分
detection.rule	4 积分
detection.tradecraft	4 积分
所有其他工具	免费

---

计划层级要求

OPTIX 会对其 REST API 强制执行计划层级访问控制。MCP 服务仅公开分析师级别的端点——无论使用哪个 API 密钥，管理员专用端点都不会通过 MCP 公开。

每个工具所需的最低 OPTIX 计划取决于其调用的底层 REST 端点：

层级	说明	可用的 MCP 工具
Free	威胁情报的基本读取权限	feed.get、search.indicator、entity.get、account.status、document.get、search.documents、detection.attack_matrix、feed.headlines、feed.cards、detection.coverage_gaps、search.ai、watchlist.list、watchlist.add、watchlist.remove、ioc.triage、feedback.vote、feed.save_view、actor.profile、actor.list
Individual	完整的分析师权限——丰富信息、检测规则、实体研究	所有 Free 工具 + ioc.context、entity.research、entity.ask、detection.rule、detection.tradecraft、incident.report、report.generate
Team	共享情报和 TAXII——多分析师组织功能	所有 Individual 工具 + TAXII 相关工作流（通过直接 API 调用）
Enterprise	组织管理和合规报告	所有 Team 工具 + 组织管理工作流（通过直接 API 调用；MCP 不公开）

注意： 管理员专用端点（审计日志、组织成员管理、提供商密钥配置、合规报告和组织概览）不会通过 MCP 服务公开。这些端点需要 org_admin 或 platform_admin 角色，且必须使用管理员范围的 API 密钥直接通过 REST API 调用。

检查您的计划

如需确认您的 API 密钥可用的层级和工具：

# Using the MCP server
result = await client.call_tool("account.status", {})
print(result)  # Shows current plan tier and available features

---

可用工具

身份验证： 所有工具都通过 MCP 客户端配置中设置的 X-API-Key 标头进行身份验证——没有 api_key 工具参数。每次请求都会向 OPTIX 后端验证密钥。

工具概览

#	工具	类别	最低层级	费用
1	feed.get	读取	Free	免费
2	search.indicator	读取	Free	免费
3	incident.report	写入	Individual	40 个积分
4	entity.get	读取	Free	免费
5	account.status	读取	Free	免费
6	document.get	读取	Free	免费
7	search.documents	读取	Free	免费
8	report.list	读取	Free	免费
9	report.get	读取	Free	免费
10	detection.attack_matrix	读取	Free	免费
11	watchlist.list	读取	Free	免费
12	watchlist.add	写入	Free	免费
13	watchlist.remove	写入	Free	免费
14	feed.headlines	读取	Free	免费
15	feed.cards	读取	Free	免费
16	ioc.context	读取	Individual	免费
17	detection.coverage_gaps	读取	Free	免费
18	search.ai	读取	Free	免费
19	entity.research	AI / 写入	Individual	15 个积分
20	entity.ask	AI / 写入	Individual	4 个积分
21	detection.rule	AI / 写入	Individual	4 个积分
22	detection.tradecraft	AI / 写入	Individual	4 个积分
23	report.generate	AI / 写入	Individual	40 个积分
24	feedback.vote	写入	Free	免费
25	feed.save_view	写入	Free	免费
26	ioc.triage	写入	Free	免费
27	actor.profile	读取	Free	免费
28	actor.list	读取	Free	免费

---

feed.get

返回来自所有 OPTIX 来源的分页精选、评分情报文档流。

使用场景：“最新的严重威胁有哪些？”／“显示最近的 TLP:AMBER 情报。”

参数	类型	必填	描述
limit	integer	否	最大条目数（1–100，默认 20）
offset	integer	否	分页时跳过的条目数
severity_filter	string	否	critical、high、medium 或 low
tlp_filter	string	否	TLP:WHITE、TLP:GREEN、TLP:AMBER、TLP:RED
since	string	否	ISO 8601 日期时间 — 仅返回此时间之后发布的文档

---

search.indicator

按值在 OPTIX 中搜索特定的失陷指标（IOC）。

使用场景：“OPTIX 发现过 185.220.101.45 吗？”／“我们对这个哈希值了解多少？”

参数	类型	必填	描述
value	string	是	要搜索的 IP、域名、哈希值、URL 或电子邮件地址
type_hint	string	否	IOC、Infrastructure、ThreatActor、MalwareFamily

---

incident.report ⚡ 40 credits

向 OPTIX 提交结构化事件报告，并生成战术情报报告。

**使用场景：**分析师完成调查后，想要创建正式的情报报告。

参数	类型	必填	描述
title	string	是	简短的事件标题（3–300 个字符）
description	string	是	完整的事件叙述
severity	string	是	critical、high、medium 或 low
tlp	string	否	TLP 分类（默认 TLP:GREEN）
indicators	string[]	否	观察到的 IOC 值
analyst_notes	string	否	补充背景或建议采取的行动

---

entity.get

按名称或 ID 获取具名威胁情报实体（威胁行为者、恶意软件、活动、CVE、技术）。

使用场景：“介绍一下 APT28”／“我们对 LockBit 了解多少？”

参数	类型	必填	描述
query	string	是	实体名称或 OPTIX 数字 ID
entity_type	string	否	ThreatActor、MalwareFamily、Tool、Campaign、Vulnerability、Technique

---

account.status

返回当前 OPTIX 积分余额、每月额度、使用情况、重置日期和账户信息。

**使用场景：**执行任何消耗积分的操作前，或分析师询问“我还有多少积分？”时。

无需参数。

---

document.get

按数字 OPTIX ID 获取特定情报文档。

**使用场景：**从其他工具获得文档 ID 后，需要查看完整元数据和摘要时。

参数	类型	必填	描述
document_id	integer	是	数字文档 ID（例如 1042）

---

search.documents

对所有 OPTIX 情报文档进行全文搜索。

使用场景：“查找有关供应链攻击的文档”／“显示本周的 Mandiant 报告。”

参数	类型	必填	描述
query	string	是	搜索字符串（至少 2 个字符）
limit	integer	否	最大结果数（1–100，默认 20）
offset	integer	否	分页时跳过的结果数
publisher	string	否	按发布者名称筛选
content_type	string	否	按内容类型筛选：ThreatResearch、MalwareAnalysis、Vulnerability 等
since	string	否	ISO 8601 日期时间 — 仅返回此时间之后发布的文档

---

report.list

列出存储在 OPTIX 中的已生成情报报告（战术、战略、行动、技术、RFI）。

使用场景：“我们制作过哪些情报报告？”/“显示所有 RFI 报告。”

参数	类型	必填	描述
limit	integer	否	报告数量上限（1–200，默认值为 20）
report_type	string	否	tactical、strategic、technical、operational、rfi
tlp_level	string	否	按 TLP 级别筛选
entity_id	integer	否	筛选引用此实体的报告

---

report.get

获取特定情报报告的完整内容。

**使用场景：**在调用 report.list 后，获取报告全文。

参数	类型	必填	描述
report_id	integer	是	数字报告标识符

---

detection.attack_matrix

获取 OPTIX MITRE ATT&CK 覆盖矩阵——情报数据中观察到的技术，以及具备检测规则的技术。

使用场景：“我们观察到了哪些 ATT&CK 技术？”/“我们是否覆盖了对 T1566 的检测？”

参数	类型	必填	描述
technique_id	string	否	特定 ATT&CK ID（例如 T1566）。省略则返回完整矩阵。

---

watchlist.list

列出分析师 OPTIX 关注列表中的所有实体。

使用场景：“我正在关注哪些实体？”/“显示我的关注列表。”

无需参数。

---

watchlist.add

将实体添加到分析师的关注列表，以便在新情报提及该实体时收到通知。

使用场景：“开始关注 APT29”（先使用 entity.get 获取实体 ID）。

参数	类型	必填	描述
entity_id	integer	是	数字 OPTIX 实体 ID

---

watchlist.remove

从分析师的关注列表中移除实体。

使用场景：“停止关注 LockBit。”

参数	类型	必填	描述
entity_id	integer	是	数字 OPTIX 实体 ID

---

feed.headlines

返回由 AI 综合生成的威胁情报头条，概述当前最活跃的威胁。

使用场景：“当前威胁态势如何？”/“给我一份简报。”

无需参数。

---

feed.cards

返回与用户档案匹配的态势感知威胁卡片，展示活跃威胁、已观察到的 TTP 和目标行业。

使用场景：“哪些威胁与我们最相关？”/“显示最近 30 天的威胁卡片。”

参数	类型	必填	描述
time_range	string	否	24h、7d（默认值）或 30d
sector	string	否	按行业筛选，例如 Finance、Healthcare

---

ioc.context

返回 IOC 的增强社区背景信息，包括分析师投票统计、共同出现的威胁行为者和恶意软件、ATT&CK 技术以及源文档。

使用场景：“分析师如何看待这个 IP？”/“这个域名已确认是恶意的吗？”

参数	类型	必填	描述
ioc_id	integer	是	IOC 的数字 OPTIX 实体 ID（使用 search.indicator 查找）

---

detection.coverage_gaps

分析情报文档，识别其中引用的 MITRE ATT&CK 技术，并确定哪些技术缺少检测覆盖。

使用场景：“我们的检测体系是否覆盖了这份报告中的技术？”/“这份文档揭示了哪些覆盖缺口？”

参数	类型	必填	描述
document_id	integer	是	数字 OPTIX 文档 ID

---

search.ai

在 OPTIX 文档和实体中使用自然语言或关键词搜索，并可选择扩展 AI 查询。

适用场景：“查找所有关于 LockBit 近期 TTP 的内容”／“搜索 Volt Typhoon。”

参数	类型	必填	描述
query	string	是	自然语言问题或关键词（至少 2 个字符）
mode	string	否	natural（由 AI 扩展，默认）或 keyword（字面匹配）

---

entity.research ⚡ 15 credits

针对某个实体启动深度 AI 研究——OPTIX 会抓取权威来源，并以结构化情报丰富该实体的资料。

适用场景：“深入研究 APT29”／“研究 LockBit 的最新情况。”

支持的实体类型：ThreatActor、MalwareFamily、Vulnerability、Tool、Campaign、Technique。

参数	类型	必填	描述
entity_id	integer	是	OPTIX 实体的数字 ID
force_refresh	boolean	否	即使已有近期结果，也强制开展新研究（默认 false）

---

entity.ask ⚡ 4 credits

利用特定实体已知的 TTP、IOC 和情报历史，生成 SIEM 威胁狩猎查询。

适用场景：“为 APT28 生成 KQL 狩猎查询”／“编写用于检测 LockBit 的 Sigma 规则。”

支持的实体类型：ThreatActor、MalwareFamily、Tool、Vulnerability。

参数	类型	必填	描述
entity_id	integer	是	OPTIX 实体的数字 ID
language	string	是	SIEM 语言：kql、splunk_spl、s1ql_v1、s1ql_v2、crowdstrike、elastic_eql、exabeam、chronicle_yara_l、sigma、carbon_black、palo_alto_xql

---

detection.rule ⚡ 4 credits

针对特定 MITRE ATT&CK 技术生成 SIEM 检测规则。

适用场景：“为 T1059.001 编写 Splunk 检测规则”／“为 PowerShell 滥用创建 KQL 规则。”

参数	类型	必填	描述
technique_id	string	是	MITRE ATT&CK 技术 ID，例如 T1059.001
language	string	是	目标 SIEM 语言（见上方列表）
technique_name	string	否	易于理解的名称，例如 PowerShell
document_id	integer	否	使用特定文档中的上下文丰富规则
entity_id	integer	否	使用特定实体中的上下文丰富规则
custom_context	string	否	其他分析人员上下文（日志来源、环境）

---

detection.tradecraft ⚡ 4 credits

生成广泛的 SIEM 狩猎查询，涵盖某个威胁行为者或恶意软件家族已知的全部作战手法。

适用场景：“在 Sentinel 中为 APT29 生成多技术狩猎查询”／“为 Volt Typhoon 编写一套全面的 Sigma 规则。”

参数	类型	必填	描述
language	string	是	目标 SIEM 语言（见上方列表）
entity_name	string	是	威胁行为者或恶意软件名称，例如 APT29
entity_type	string	是	ThreatActor 或 MalwareFamily
entity_id	integer	否	用于丰富查询的 OPTIX 实体 ID
technique_entries	array	否	可选列表 {techniqueId, techniqueName, description}，用于限定狩猎范围

---

report.generate ⚡ 40 credits

利用 OPTIX 的文档和实体语料库生成战略、行动、技术或 RFI 情报报告。

适用场景：“撰写有关勒索软件威胁态势的战略报告”／“生成关于 APT40 的 RFI。”

参数	类型	必填	描述
title	string	是	报告标题（3–300 个字符）
query	string	是	使用自然语言描述报告主题
report_type	string	否	tactical（默认）、strategic、technical、operational、rfi
tlp	string	否	TLP 分类（默认 TLP:GREEN）

---

feedback.vote

针对 OPTIX 情报文档提交相关性投票（赞成或反对）。社区投票可改善 OPTIX 评分和信息流个性化。

使用场景：“给这份文档投赞成票——它非常相关” / “给这份文档投反对票，它与我们无关。”

参数	类型	必填	说明
document_id	integer	是	OPTIX 文档的数字 ID
vote	string	是	up 或 down
scope	string	否	platform（所有分析师，默认值）或 org（仅限你的组织）

---

feed.save_view

保存命名的信息流筛选配置，供分析师之后调用。

使用场景：“将此筛选条件保存为‘本周的严重恶意软件’” / “收藏我当前的视图。”

参数	类型	必填	说明
name	string	是	视图名称（1–200 个字符）
filters	object	否	筛选配置。常用键：severity、tlp、contentType、publisher、publishedAfter

---

ioc.triage

为一个或多个 IOC 应用分诊判定，记录分析师对其处置方式的判断。

使用场景：“将这些 IP 标记为已确认的恶意对象” / “将此域名标记为误报。”

参数	类型	必填	说明
entity_ids	integer[]	是	OPTIX IOC 实体 ID 列表（使用 search.indicator 查找）
status	string	是	confirmed、false_positive、benign、expired、monitoring 或 unresolved
scope	string	否	platform（全局判定，默认值）或 org（组织范围）

---

actor.profile

通过一次调用返回威胁行为者的丰富易读档案——无需后续调用即可了解核心信息。接受行为者名称和已知别名，并自动将其解析为规范实体名称。

使用场景：“介绍一下 APT28” / “我们对 Fancy Bear 有哪些了解？” / “查看 Lazarus Group 的档案。”

响应内容包括：行为者档案和描述、所有已知别名、带有战术名称的 ATT&CK 技术、按类型分组的 IOC（IP、域名、哈希、URL）、关联的恶意软件家族、相关情报报告数量，以及（如有）最新报告摘要。若要进一步开展深入 AI 研究，请使用 entity.research（15 个积分）。若要生成 SIEM 狩猎查询，请使用 entity.ask（4 个积分）。

参数	类型	必填	说明
actor_name	string	是	威胁行为者的名称或已知别名（例如 APT29、Fancy Bear、LockBit）。不区分大小写。

---

actor.list

列出工作区当前在 OPTIX 中跟踪的所有威胁行为者，包括规范名称、已知别名、类型、置信度以及首次/最后发现日期。可先用此工具浏览完整的行为者清单，再通过 actor.profile 深入查看特定档案。

使用场景：“我们正在跟踪哪些行为者？” / “我们掌握哪些威胁组织的情报？”

参数	类型	必填	说明
limit	integer	否	可选的结果数量上限。省略则检索所有跟踪中的行为者。

---

Glama 注册表检查

当 OPTIX MCP 服务列在 Glama 上时，注册表会构建 Docker 镜像并连接到服务以检测可用工具。由于 Glama 没有真实的 OPTIX API 密钥，因此必须暂时绕过身份验证。

在 Glama 服务配置中，将 占位参数 字段设置为：

{"OPTIX_SKIP_AUTH": "true"}

设置 OPTIX_SKIP_AUTH=true 后，服务会正常启动，并接受未经身份验证的 MCP 会话以列出工具。工具的执行仍会返回相应错误，因为没有真实的 API 密钥——只有 list_tools() 会成功，而这正是 Glama 评估工具质量所需的全部内容。

在 OPTIX_SKIP_AUTH 默认为 false 的常规部署中，此标志不会产生任何影响。

---

健康检查端点

GET /health 无需身份验证即可返回服务状态：

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

如果 optix_connected 为 false，状态将为 degraded，且在 OPTIX 后端恢复可访问之前，工具调用都会失败。

---

错误处理

所有工具都会返回结构化错误消息，而不是向 AI 客户端抛出异常：

错误类型	原因	响应
Authentication error	API 密钥无效或缺失	提示用户检查其 OPTIX API 密钥
Insufficient credits	余额低于操作所需额度	调用 account.status 并等待额度重置日期
Not found	实体、文档或报告不存在	验证 ID 或名称，然后重试
OPTIX API error	后端错误或验证失败	包含原始 OPTIX 错误消息以便诊断
Validation error	工具参数无效	包含字段级详情以便修正调用