Sophos Fusion MCP Server (formerly Sophos Central)

Sophos Fusion MCP Server (formerly Sophos Central)

Unofficial project, not from Sophos. This is a personal project by an individual. It isnot an official Sophos product and it is not built, endorsed, supported, or warranted bySophos. It calls the public Sophos APIs using credentials you supply. Use it at your ownrisk, and raise problems as issues on this repository rather than with Sophos support.

MCP (Model Context Protocol) server for the Sophos Fusion and Sophos Central APIs. Supports partner, organisation, and single-tenant credential types with automatic region routing. 310 tools covering 22 Sophos API namespaces: the Sophos Central REST APIs plus the Sophos Fusion GraphQL APIs (sophos_fusion_*). Install it as a Claude Desktop extension (.mcpb), run it with npx, or host it yourself over streamable HTTP.

The npm package, the .mcpb bundle and the binaries keep the sophos-central-mcp-server name so existing installs update in place.

Prerequisites

You need these before any of the install options below.

Sophos Central API credentials

Every install method needs a Client ID and Client Secret. The same credential authorises both the Sophos Central REST tools and the Sophos Fusion GraphQL tools; there is no second credential. The credential type decides what the server can see:

• Tenant-level: In Sophos Central, go to Settings > API Credentials Management and create a new credential. The server operates on that one tenant.
• Partner-level: In the Sophos Partner Dashboard, create API credentials under Settings > API Credentials. The server can query every tenant the partner manages.
• Organisation-level: In Sophos Central Enterprise, use Global Settings > API Credentials Management. Same cross-tenant behaviour as partner credentials.

Node.js 20 or later (npm and self-hosted installs only)

The .mcpb bundle for Claude Desktop does not need Node.js on your machine: Claude Desktop ships its own Node.js runtime and the bundle carries the server and all of its dependencies. Install Node.js 20+ only if you use the Claude Code or self-hosted options.

Install

Pick one:

Option 1: Claude Desktop extension (.mcpb, recommended)

The .mcpb file is an MCP Bundle: a zip containing the built server, its production dependencies, and a manifest that tells Claude Desktop how to run it and which settings to ask for. No terminal and no config file edits.

1. Download sophos-central-mcp-server-<version>.mcpb from the latest GitHub release.
2. Open the file with Claude Desktop. Double-clicking it works on macOS and Windows. You can also go to Settings > Extensions > Advanced settings, find the Extension Developer section, click Install Extension... and pick the file.
3. Claude Desktop shows the extension details and asks for your Sophos Central Client ID and Client Secret. Both fields are marked sensitive in the manifest, so Claude Desktop keeps them in the operating system's secure storage instead of a config file.
4. Click Install, make sure the extension is enabled, then start a new chat. The sophos_* tools are available straight away.

To update, download the newer .mcpb and install it the same way. To remove it, open Settings > Extensions and uninstall the extension.

To change the credentials later, open Settings > Extensions and click this extension. The Sophos Central Client ID and Client Secret fields are editable there. They are stored in the operating system's secure storage and show masked, so you replace a value rather than read the old one back. The server reads them at startup, so toggle the extension off and on, or restart Claude Desktop, if a change does not take effect.

The bundle runs the server in stdio mode and sets TRANSPORT=stdio for you. Which tools you get depends on the credential type, exactly as with the other install options: partner and organisation credentials unlock the cross-tenant tools, tenant credentials do not.

Option 2: Claude Code

Requires Node.js. Run this once in your terminal. The -e flags save the credentials permanently to Claude Code's MCP config so you don't need to re-export them each session:

macOS / Linux:

claude mcp add sophos-central \
  -e SOPHOS_CLIENT_ID="your-client-id" \
  -e SOPHOS_CLIENT_SECRET="your-client-secret" \
  -e TRANSPORT="stdio" \
  -- npx -y sophos-central-mcp-server

Windows (Command Prompt):

claude mcp add sophos-central ^
  -e SOPHOS_CLIENT_ID="your-client-id" ^
  -e SOPHOS_CLIENT_SECRET="your-client-secret" ^
  -e TRANSPORT="stdio" ^
  -- cmd /c npx -y sophos-central-mcp-server

Option 3: Self-hosted with npm (streamable HTTP or stdio)

Use this when you want to run the server yourself, on a workstation, a jump box, or in a container, for any MCP client that speaks streamable HTTP or can spawn a stdio process. Nothing here depends on the .mcpb bundle.

Install from npm:

npm install -g sophos-central-mcp-server

Or from source:

git clone https://github.com/Aaronjacobs000/sophos-mcp.git
cd sophos-mcp
npm install
npm run build

Configure. Either export the variables in your shell or put them in a .env file in the directory you start the server from. The full table is under Configuration.

SOPHOS_CLIENT_ID=your-client-id
SOPHOS_CLIENT_SECRET=your-client-secret
PORT=3100
TRANSPORT=http

Run:

sophos-central-mcp      # global npm install
npm start               # from a source checkout

With TRANSPORT=http (the default) the server listens on http://127.0.0.1:3100/mcp and answers GET /health with {"status":"ok","server":"sophos-central-mcp-server"}. The MCP endpoint is stateless: every request gets a fresh transport. Point any streamable HTTP client at it, for example Claude Code:

claude mcp add --transport http sophos-central http://127.0.0.1:3100/mcp

With TRANSPORT=stdio the server speaks MCP over stdin/stdout and is meant to be spawned by the client, which is what Options 1 and 2 do for you.

The HTTP server binds to 127.0.0.1 only and has no authentication of its own. If it needs to be reachable from another host, put it behind something that adds TLS and auth (an SSH tunnel or an authenticating reverse proxy) rather than changing the bind address.

Build the .mcpb yourself (maintainers)

The bundle is produced by scripts/build-mcpb.mjs using the mcpb CLI, which is a dev dependency. From a source checkout:

npm install
npm run build:mcpb

The script:

1. Compiles TypeScript to dist/ (via npm run build).
2. Rewrites manifest.json so its version matches package.json and its tools list matches every registerTool call in src/tools/. Commit the result. The manifest in git is always the one that was last built.
3. Validates the manifest with mcpb validate.
4. Stages dist/, package.json, LICENSE, and manifest.json in build/mcpb/ and runs npm ci --omit=dev there, so only production dependencies are bundled. .mcpbignore adds a few exclusions on top of the CLI's defaults.
5. Packs the staging directory into release/sophos-central-mcp-server-<version>.mcpb.

build/ and release/ are git-ignored. To inspect a bundle without installing it, npx mcpb info release/<file>.mcpb prints its size and signature state, and npx mcpb unpack release/<file>.mcpb <dir> extracts it. Signing is optional; npx mcpb sign --self-signed release/<file>.mcpb adds a self-signed signature if you want one.

Tests (maintainers)

npm test

Builds, then runs the node:test suites in test/ with fetch stubbed: the Fusion GraphQL transport (including the HTTP 200 with errors case), the QL builder, the reference-data cache, and the path-keyed retry for the intermittent case-write fault, the migration guard, and a registration check that lists all 310 tools over an in-memory transport and checks the descriptions for the measured warnings. Nothing in npm test reaches Sophos.

To exercise the Fusion tools against a live tenant, put credentials in .env (or export them) and run:

node scripts/fusion-smoke.mjs                  # read-only, tenant credential
node scripts/fusion-smoke.mjs <tenant-id>      # read-only, partner or organisation credential
node scripts/fusion-smoke.mjs --write          # plus the Fusion write tools on one new case
node scripts/fusion-smoke.mjs --write-classic  # plus the Classic case tools on one new case
node scripts/fusion-smoke.mjs --all            # everything

It spawns the built server over stdio and calls the tools through an MCP client, so what runs is what a host runs. Read-only mode covers the reference data, the case list with filter and cursor variants, the newest case by short ID, its evidence, summary, comments and files, the detection search, the not-found and legacy-ID refusals, and the Classic side: on a migrated tenant the migration refusal, otherwise the six Classic read tools. --write creates one case titled MCP smoke test <timestamp> (managed_by CUSTOMER), exercises comment add, edit and delete with the mention read-back, link create, update and delete, tag merge and replace, evidence add and remove_all, file upload, list and soft delete, the verdict clear on reopen, the one way door on new and the closed-case freeze, then closes it with a verdict and archives it (Fusion has no delete). --write-classic creates, updates and deletes one Classic case; the Cases API requires an assignee and a detection that still exists, so set SMOKE_CLASSIC_ASSIGNEE (a tenant admin email) and, if needed, SMOKE_CLASSIC_DETECTION_ID (a recent detection ID). Every write is listed at the end. Existing cases are never modified.

Cutting a release: bump version in package.json, run npm run build:mcpb, commit package.json, package-lock.json, and manifest.json, tag, and attach the .mcpb from release/ to the GitHub release. Publish to npm as before so the Claude Code and self-hosted options pick up the same version.

Features

• Universal caller support: Works with partner, organisation, and tenant-level API credentials
• Multi-tenant: Partner/org callers can query across all managed tenants
• Partner gap analysis: Single-call sales opportunity report across all managed tenants. Fetches health data in parallel and returns a compact ranked list of security gaps per customer
• Auto region routing: Discovers tenant data regions via /whoami/v1 and routes requests to the correct regional API host
• Token lifecycle: Automatic OAuth2 token refresh before expiry
• Rate limit handling: Retry with backoff on 429 responses
• Dual transport: stdio (Claude Desktop, Claude Code, and the .mcpb bundle) or streamable HTTP (self-hosted)
• One-click install: Ships as a Claude Desktop extension (.mcpb) with credentials held in the OS secure store
• Two API generations: the Sophos Central REST APIs and the Sophos Fusion GraphQL APIs on one credential, with sophos_fusion_* tools for the GraphQL side
• Migration aware: the Classic case and detection tools refuse a tenant that has moved to Sophos Fusion and name the sophos_fusion_* tool to use instead
• Full API coverage: 310 tools across endpoints, alerts, policies, firewalls, web filtering, licensing, audit events, email, mobile, XDR, cases, SIEM, and more

Screenshots

Querying tenants and drilling into endpoint status:

Tenant health audit with full category breakdown:

Configuration

Applies to the Claude Code and self-hosted options. The Claude Desktop extension asks for the credentials in its install dialog and sets TRANSPORT=stdio itself.

Copy .env.example to .env and set your credentials:

SOPHOS_CLIENT_ID=your-client-id
SOPHOS_CLIENT_SECRET=your-client-secret
PORT=3100
TRANSPORT=http

Tools

Two API generations

The server speaks to two Sophos API generations on one credential:

• Sophos Central REST APIs (retained). Every tool without the fusion prefix. Regional hosts, discovered from /whoami/v1.
• Sophos Fusion GraphQL APIs (new, 18/09/2026). The sophos_fusion_* tools. One endpoint, https://api.taegis.sophos.com/graphql, same token, same X-Tenant-ID header. Filters are written in Fusion Query Language (QL). Case types, statuses and verdicts are tenant reference data resolved to IDs at runtime, case severity is an integer (2 to 10), and assignees are Subject IDs, not email addresses. A GraphQL failure arrives as HTTP 200 with an errors array; the client treats that as an error, and a partial response (data plus errors) is returned with a warnings list rather than as a clean result.

Sophos is moving tenants to Fusion over the coming months (the upgrade centre announces each account's slot). This is a point in time change, not a fallback: once a tenant has moved, the Classic Cases and Detections REST APIs reference the pre-migration Sophos Central objects, so their answers are wrong rather than stale. The Classic tools therefore check which world a tenant is in before every call, using the Fusion case reference data (a tenant that has not moved gets an empty case type list), and refuse a migrated tenant with a message naming the sophos_fusion_* tool to use. For a tenant that has not moved they stay correct and carry no deprecation label. Fusion holds a separate case set (a UUID plus a CSE##### short ID) and neither ID form resolves in the other API. Live Discover and XDR Query are unaffected. Data Lake search over GraphQL has not shipped (Sophos says October 2026), so sophos_run_xdr_query stays on the SQL XDR Query API. Fusion tools for events, threat timeline and live endpoint search are planned.

Two Fusion case writes, createCase and addEvidenceToCase, fail 74% of the time with not allowed on partnerPreferences from investigations-v2. It is an intermittent downstream fault, not authorisation: the identical call succeeds on retry, and updateCase does not carry the fault at all. Measured on a live tenant 22/09/2026: 111 faults in 150 calls, drifting from 60% to 85% across four samples six minutes apart. The client retries a call whose first error path is partnerPreferences, and only that, up to 20 times with a short backoff, which leaves about 1 call in 410 failing at the measured rate and about 1 in 26 at the worst rate observed; an error naming the operation in its path is a real input or permission error and surfaces at once.

Partner & Organisation (18 tools)

These tools are only available with partner or organisation-level credentials. They operate across all managed tenants.

Alerts (4 tools)

Endpoints (18 tools)

Endpoint Settings (30 tools)

Endpoint Migrations (7 tools)

Policies (6 tools)

Endpoint Groups (7 tools)

Exclusions & Allow/Block Lists (9 tools)

Account Health (3 tools)

Directory Users & Groups (17 tools)

Admin Management (13 tools)

Cases (9 tools)

Sophos Central Cases REST API. Correct for a tenant that has not moved to Fusion, and the only way to read its legacy cases (IDs like 1-598868). Refused for a tenant that has moved, with a pointer to the sophos_fusion_* tool to use (see "Two API generations").

Fusion Cases (21 tools)

Sophos Fusion Cases GraphQL API v2. Case IDs are UUIDs; short IDs (CSE00001) are accepted and resolved. Severity is 2 informational, 4 low, 6 medium, 8 high, 10 critical. Detection severity inside the case summary is a 0 to 1 float, a different scale from both the case severity and the Classic REST 0 to 10 detection severity; none of them convert. There is no delete: close the case (with a verdict when its type needs one), then archive it.

managed_by is required on create and decides who works the case: PROVIDER hands it to Sophos MDR, CUSTOMER keeps it self managed. It cannot be changed afterwards, and a case created without it is unclaimed, so the tool never omits it. Detection and event IDs on the evidence tools are six section resource names (alert://priv:event-filter:123456:1789526908712:<uuid>), which sophos_fusion_search_detections returns. Evidence writes are queued jobs that land category by category (an add showed after about 5 seconds, a three category removal took about 25 seconds), so read the evidence back with a poll; adding a detection also attaches its linked asset and events, and removing it does not retract them (remove_all does). Comment @mentions (@authorized_contacts, @customer, @sophos) fire wherever they appear, including in prose, and an unrecognised token is dropped silently, so the comment tools read the stored mentions back. Tags are merged on update unless replace_tags is set. File deletion is soft. Split and merge are irreversible and need a confirmation argument.

Fusion Detections (1 tool)

Sophos Fusion Detections GraphQL API v2. One QL search replaces the Classic run, poll, results triple. Source keyword alert; working example from alert severity >= 0.1 EARLIEST=-90d. Severity is a 0 to 1 float.

Detections (6 tools)

Sophos Central Detections REST API, async: start a query, poll for completion, then fetch results. Refused for a tenant that has moved to Fusion, with a pointer to sophos_fusion_search_detections.

SIEM (2 tools)

XDR Data Lake (9 tools)

Async API: submit SQL queries against historical telemetry.

Live Discover (4 tools)

Async API: run OSquery SQL on live endpoints. Rate limited to 10 runs/minute, 500/day.

Firewall (21 tools)

Config import/export requires the firewall to run SFOS v22 MR2 or later, bemanaged by Sophos Central, and hold an active license. On an HA pair, targetthe primary node (the auxiliary rejects config operations). The exportedarchive can appear in storage a couple of minutes after the transactionreports finished; sophos_download_firewall_backup retries automaticallyfor about 3 minutes to cover that window.

Email Protection (29 tools)

Mobile Device Management (32 tools)

DNS Protection (5 tools)

Cloud Security (5 tools)

Wi-Fi (3 tools)

User Activity (2 tools)

Audit Events (1 tool)

Licensing (2 tools)

Web Filtering (16 tools)

Switch Management (3 tools)

Accounts / Access Tokens (4 tools)

Business Automation (4 tools)

Distributor-scoped: requires distributor-entitled credentials and anX-Distributor-ID.

Tenant context

For partner/org callers, every tenant-scoped tool requires a tenant_id parameter. Use sophos_list_tenants first to discover available tenant IDs.

For tenant-level callers, tenant_id is optional and defaults to the authenticated tenant.

Architecture

Authenticate (OAuth2 client credentials)
    |
    v
/whoami/v1 -> Discover identity type (partner | organization | tenant)
    |
    v
If partner/org: enumerate tenants, cache {tenantId -> apiHost}
    |
    v
Register tools based on identity type
    |
    v
Per tool call: resolve tenant -> regional API host -> execute request
Per sophos_fusion_* call: resolve tenant -> POST api.taegis.sophos.com/graphql -> inspect data and errors

Key decisions

• Dynamic tool registration: Only tools valid for the caller type are exposed to the LLM
• Explicit tenant context: Partner/org callers must specify tenant_id to prevent cross-tenant accidents
• Stateless HTTP: Each MCP request creates a fresh transport instance (no session affinity)
• Localhost binding: HTTP server binds to 127.0.0.1 only

Project Structure

src/
├── index.ts                     # Entry point, server bootstrap
├── config/config.ts             # Environment config
├── auth/token-manager.ts        # OAuth2 token lifecycle
├── client/
│   ├── sophos-client.ts         # REST client with region routing (Sophos Central)
│   ├── fusion-client.ts         # GraphQL client (Sophos Fusion), 200-with-errors handling, path-keyed retry
│   └── tenant-resolver.ts       # Whoami + tenant cache
├── fusion/
│   ├── queries/cases.ts         # Cases v2 GraphQL documents
│   ├── queries/detections.ts    # Detections v2 documents: the case summary lookup and the QL search
│   ├── case-reference-data.ts   # Per-tenant cache of case types, statuses, verdicts
│   ├── cases-ql.ts              # QL builder for the cases search
│   ├── format.ts                # Severity scales, timestamps, ID checks, mentions, tags, detection rows
│   ├── migration.ts             # Has this tenant moved to Fusion? Gates the Classic case and detection tools
│   └── types.ts                 # Fusion response types
├── tools/
│   ├── helpers.ts               # Shared response formatting
│   ├── fusion-cases.ts          # Sophos Fusion cases (GraphQL)
│   ├── fusion-detections.ts     # Sophos Fusion detection search (GraphQL)
│   ├── tenants.ts               # Tenant listing (partner/org only)
│   ├── partner.ts               # Partner admin, roles, billing (partner/org only)
│   ├── alerts.ts                # Alert list, get, acknowledge, search
│   ├── endpoints.ts             # Endpoint CRUD, scan, isolate, tamper, forensics
│   ├── endpoint-settings.ts     # Installer, web control, exploit mitigation, IPS, etc.
│   ├── endpoint-migrations.ts   # Migration jobs, software packages
│   ├── health.ts                # Account health, gap analysis
│   ├── directory.ts             # Users, user groups, group membership
│   ├── admin-management.ts      # Admin CRUD, roles, permission sets
│   ├── policies.ts              # Policy CRUD, clone
│   ├── groups.ts                # Endpoint group CRUD, membership
│   ├── exclusions.ts            # Scanning exclusions, allowed/blocked items
│   ├── cases.ts                 # Investigation cases, detections, MITRE
│   ├── detections.ts            # Detection queries (async)
│   ├── siem.ts                  # SIEM events and alerts
│   ├── xdr.ts                   # XDR Data Lake queries (async)
│   ├── live-discover.ts         # Live Discover queries (async)
│   ├── firewall.ts              # Firewall CRUD, firmware, groups, threat feed, config import/export
│   ├── email.ts                 # Quarantine, mailboxes, message actions
│   ├── mobile.ts                # Mobile devices, groups, actions, policies
│   ├── dns-protection.ts        # DNS locations
│   ├── cloud-security.ts        # Cloud security profiles, assets
│   ├── wifi.ts                  # Wi-Fi MAC filtering
│   └── user-activity.ts         # User attestations
└── types/sophos.ts              # Sophos API response types

Packaging files at the repo root: manifest.json (MCPB manifest, regenerated by the build), scripts/build-mcpb.mjs (bundle builder), and .mcpbignore (extra exclusions applied when packing). schemas/fusion/ holds the five Fusion GraphQL schemas as downloaded from https://developer.sophos.com/assets/graphql/<api>.graphql on 21/09/2026, unmodified, for reference and for diffing when Sophos changes them. test/ holds the node:test suites and scripts/fusion-smoke.mjs the live check.

Security

• Credentials are read from environment variables only, never logged
• JWT tokens are held in memory with automatic refresh
• HTTP server binds to 127.0.0.1 (localhost only)
• Write actions have destructiveHint annotations so clients can warn users
• Partner/org callers require explicit tenant_id on every call
• With the .mcpb install, Claude Desktop holds the credentials in the OS secure store (they are sensitive in manifest.json) and hands them to the server as environment variables when it starts the process

License

MIT