# Sophos Central MCP (read-only)

Unofficial MCP server exposing **read-only** Sophos Central information: antivirus/endpoint
health, firewall inventory and status, switch settings, and email protection (quarantine,
mailboxes, clawback status). Built against the public [Sophos Central APIs](https://developer.sophos.com/apis)
using the vendor's own [Postman collection](https://github.com/sophos/sophos-central-apis-postman)
as the source of truth for paths, headers, and response shapes.

Not affiliated with, endorsed by, or sponsored by Sophos.

## Scope: read-only, by design

This server implements **no mutating endpoints at all** — not behind a flag, not behind a
deny-list, they simply aren't wired up. Excluded on purpose:

- Endpoint: isolate/un-isolate, tamper-protection changes, policy CRUD, scans, forensic
  logs/memory dumps, endpoint-group CRUD, migrations.
- Firewall: firmware upgrades, reboot/other firewall actions, firewall-group CRUD, MDR
  threat-feed indicator writes.
- Switch: MAC-filter list writes.
- Email: quarantine/post-delivery-quarantine release or delete, clawback initiation,
  mailbox create/update/delete/bulk, alias/delegate/distribution-list-owner writes,
  attachment strip/reattach/download.

If you need any of those, they're documented in Sophos's API but not implemented here —
open an issue or add a tool following the same pattern in `src/tools.ts`.

## Authentication

Sophos Central uses OAuth2 client-credentials. Create an **API Credential** in
Sophos Central under **Settings > API Credential Management**, which gives you a
Client ID and Client Secret scoped to one tenant (or an organization/partner account
managing multiple tenants).

```
SOPHOS_CLIENT_ID=...
SOPHOS_CLIENT_SECRET=...
```

The server exchanges these for an access token (`https://id.sophos.com/api/v2/oauth2/token`),
resolves the caller's tenant ID and data-region API host via `whoami`, and sends
`X-Tenant-ID` (or `X-Organization-ID`/`X-Partner-ID` for those credential types) on every
subsequent request. No tenant ID needs to be configured manually.

## Install

```bash
npm ci && npm run build
```

Then point your MCP client at `dist/entry.js`:

```json
{
  "mcpServers": {
    "sophos-central": {
      "command": "node",
      "args": ["/path/to/sophos-central-mcp/dist/entry.js"],
      "env": {
        "SOPHOS_CLIENT_ID": "...",
        "SOPHOS_CLIENT_SECRET": "..."
      }
    }
  }
}
```

## Tools

| Tool | Domain | Description |
| --- | --- | --- |
| `sophos_whoami` | — | Resolved tenant/organization/partner identity and API region |
| `sophos_list_alerts` | Common | Cross-product alert feed (endpoint, firewall, email, etc.) |
| `sophos_get_alert` | Common | Get one alert by ID |
| `sophos_list_endpoints` | Endpoint | Device inventory with health/isolation/tamper status |
| `sophos_get_endpoint` | Endpoint | Get one endpoint by ID |
| `sophos_get_endpoint_isolation_status` | Endpoint | Isolation status for one endpoint |
| `sophos_get_endpoint_tamper_protection` | Endpoint | Tamper protection status for one endpoint |
| `sophos_list_endpoint_groups` | Endpoint | List device groups |
| `sophos_get_endpoint_group` | Endpoint | Get one device group |
| `sophos_list_endpoint_group_members` | Endpoint | List endpoints in a group |
| `sophos_list_firewalls` | Firewall | Firewall inventory, firmware, connection/sync status |
| `sophos_list_firewall_groups` | Firewall | List firewall groups |
| `sophos_get_firewall_group_sync_status` | Firewall | Per-firewall config sync status within a group |
| `sophos_get_firewall_mdr_threat_feed` | Firewall | MDR threat feed config for one firewall |
| `sophos_get_switch_mac_filtering` | Switch | Tenant-wide MAC filter allow-list |
| `sophos_list_switch_tasks` | Switch | Async switch config-push task status |
| `sophos_search_quarantine_messages` | Email | Search quarantined email (malware/spam/impersonation) |
| `sophos_get_quarantine_message_preview` | Email | Preview one quarantined message |
| `sophos_get_quarantine_message_urls` | Email | URLs found in one quarantined message |
| `sophos_get_quarantine_message_attachments` | Email | Attachment metadata for one quarantined message |
| `sophos_search_post_delivery_quarantine_messages` | Email | Search post-delivery quarantine |
| `sophos_get_post_delivery_quarantine_message_preview` | Email | Preview one post-delivery-quarantined message |
| `sophos_list_mailboxes` | Email | List protected mailboxes |
| `sophos_get_mailbox` | Email | Get one mailbox by ID |
| `sophos_get_message_clawback_status` | Email | Status of a clawback request |

## Sophos's own API surface notes

- **Switch API is currently narrow.** The vendor's own Postman examples only cover
  MAC-filter settings and async task status — no separate switch-device inventory endpoint
  is documented there as of this writing.
- **Endpoint restore/file-browsing and firewall traffic logs are not covered** by this API
  surface at all; Sophos Central's console remains the place for those.