fieldeffect-mcp

MCP server for Field Effect (Covalence MDR — managed detection & response). Exposes the Field Effect MDR Portal REST API's organization, endpoint device, and Active Response reporting endpoints as MCP tools.

Naming note: MSPbots' own integration is registered as "Field Effect" (subjectCode=FIELDEFFECT); the vendor's product name is "Covalence" / "Field Effect MDR". This MCP covers exactly the 4 GET endpoints MSPbots itself has configured — see Known Gaps below for why the scope stops there.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own API key via a header, used only for the lifetime of that single request.
• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.
• Entry points: POST /mcp (MCP protocol) and GET /health (health check).
• Default port: 8080 (configurable via MCP_HTTP_PORT).

Authentication

Field Effect authenticates with a static API key, created in the API section of the Field Effect MDR Portal. MSPbots' own integration convention sends this key as an Authorization: Bearer <api-key> header, and this server forwards it exactly that way.

HEADER 授权参数说明

Header	类型	是否必填	默认值	枚举值	字段描述	Example
X-FieldEffect-Api-Key	string	是	无	无	Field Effect MDR Portal API Key，转发为上游 Authorization: Bearer <key> 请求头	a1b2c3d4e5f6...

Missing the header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-FieldEffect-Api-Key header",
  "required_headers": ["X-FieldEffect-Api-Key"],
  "optional_headers": []
}

Environment Variables

Variable	类型	是否必填	默认值	说明
MCP_HTTP_PORT	int	否	8080	HTTP 监听端口
MCP_HTTP_HOST	string	否	0.0.0.0	HTTP 监听地址
FIELDEFFECT_BASE_URL	string	否	https://services.fieldeffect.net/v1	Field Effect API 基础 URL

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)
• GET /health — health check, returns {"status": "ok", "service": "fieldeffect-mcp", "transport": "http"}

Tool List

All 4 tools are plain GET calls, matching exactly how MSPbots itself calls this integration today.

Tool	功能	参数
fieldeffect_get_organizations	列出该 API Key 可见的所有组织（客户）	无
fieldeffect_get_endpoint_devices	列出所有端点设备（含风险等级/分数），分页返回	page, per_page（均可选，见 Known Gaps）
fieldeffect_get_endpoint_device_antivirus_details	获取指定端点设备的杀毒软件状态详情	device_id（必填）
fieldeffect_get_active_response_actions	列出 Active Response 响应事件（如设备隔离），分页返回	page, per_page（均可选，见 Known Gaps）

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-FieldEffect-Api-Key: <your-fieldeffect-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "fieldeffect_get_organizations",
      "arguments": {}
    }
  }'

Live-verified (2026-07-29) against a real MDR Portal API key: all 4 tools were called end-to-end through this running server — fieldeffect_get_organizations returned 41 real organizations, fieldeffect_get_endpoint_devices returned a paginated list (1719 devices total across 18 pages), fieldeffect_get_endpoint_device_antivirus_details returned successfully (204, no AV data for that particular device — not an error), and fieldeffect_get_active_response_actions returned 200.

API Reference

• Overview (public, no login required): https://support.fieldeffect.com/en/support/solutions/articles/16000206018-field-effect-apis-overview
• The full interactive Swagger/OpenAPI documentation is only accessible from inside the MDR Portal's own Support section — it requires being logged into a Field Effect MDR Portal account, not just having an API key. No public Swagger/OpenAPI spec was found, and probing common spec paths (/swagger.json, /v1/openapi.json, /v1/api-docs, etc.) directly against services.fieldeffect.net all returned 404.

Known Gaps

• Scope is exactly MSPbots' 4 configured endpoints, not the vendor's full API surface — same situation as bvoip-mcp/contactscience-mcp/ dropsuite-mcp earlier in this program: the vendor's fuller API reference requires a portal login this session doesn't have, so there was no larger accessible spec to weigh a broader scope against.
• page/per_page parameters on get_endpoint_devices and get_active_response_actions are inferred, not confirmed — the vendor doesn't publish these endpoints' accepted query parameters anywhere accessible. They were added because the live response shape ({"items": [...], "page": 1, "per_page": 100, "total": ..., "pages": ..., "has_next": ..., "has_prev": ...}) strongly suggests a standard page/per_page pagination scheme, but this has not been verified by actually passing those parameters and confirming a changed result.
• Response field shapes are whatever the live API returns — not independently verified against a schema, since none is publicly available.