Sophos XGS MCP Server

A Model Context Protocol (MCP) server for the Sophos XGS Firewall XML API. Gives AI assistants like Claude visibility into your firewall configuration, and — only when you explicitly enable it — the ability to change it.

Read-only by default. The write tools are not registered unless SOPHOS_ENABLE_WRITE=1 is set. Without it this server cannot modify the appliance.

Features

• 60+ read tools covering firewall rules, NAT, VPN, web filtering, network config,

routing, DHCP, DNS, IPS, SSL/TLS inspection, and admin settings

• Opt-in write tools — create, update, delete and preview any entity
• Read-modify-write updates — updates never send a bare delta (see below)
• Secret redaction — passwords, hashes and pre-shared keys never reach the client
• XML injection protection — tag validation and escaping on every value; no tool

accepts raw XML

• Credential isolation — credentials come from protected config files
• Scoped TLS handling — the self-signed cert bypass is per-request, not global

Tools

Appliance quirks these tools cannot hide

• `list_schedules` does not return the SFOS built-ins. All The Time is missing

from the result and from an exact-name filter, yet it is the most-used schedule in a typical ruleset. Absence from this list is not evidence that a schedule does not exist — check the rules that reference it.

• Some entity names are plural where the object is singular. Service definitions

live under Services; a Get on Service fails with 529 Input request module is Invalid. That code means unknown entity, not no such object — if raw_api_query returns it, try the other spelling before concluding the object is gone.

Prerequisites

• Node.js 18+
• Sophos XGS Firewall with the XML API enabled (port 4444 by default)
• An API admin account. For read-only use, a restricted profile is strongly

recommended; see Write access.

Enabling the Sophos XML API

1. Log into your Sophos XGS web admin
2. Go to Backup & firmware > API
3. Enable the API and allow access from the host running the MCP server

Setup

1. Install

git clone https://github.com/Leon69924/sophos-xgs-mcp.git
cd sophos-xgs-mcp
pnpm install
pnpm build

2. Configure credentials

mkdir -p ~/.config/sophos-xgs
chmod 700 ~/.config/sophos-xgs

Create ~/.config/sophos-xgs/config.json with one profile per firewall. activeProfile selects which firewall the tools target; switch at runtime with the switch_profile tool (the switch is persisted to this file):

{
  "activeProfile": "main",
  "profiles": {
    "main": {
      "host": "your-sophos-hostname-or-ip",
      "port": "4444",
      "username": "your-api-user",
      "description": "optional free-text note"
    }
  }
}

Create ~/.config/sophos-xgs/credentials-<profile> with just the password, one file per profile:

echo -n "your-password" > ~/.config/sophos-xgs/credentials-main
chmod 600 ~/.config/sophos-xgs/config.json ~/.config/sophos-xgs/credentials-main

Alternatively, use environment variables — they override the config file entirely (profile switching is disabled while they are set):

export SOPHOS_HOST=your-sophos-hostname-or-ip
export SOPHOS_PORT=4444
export SOPHOS_USERNAME=your-api-user
export SOPHOS_PASSWORD=your-password

3. Add to your MCP client

For Claude Code, add to ~/.mcp.json:

{
  "mcpServers": {
    "sophos-xgs": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sophos-xgs-mcp/dist/index.js"]
    }
  }
}

Write access

Write tools are registered only when SOPHOS_ENABLE_WRITE=1 is present in the server's environment:

{
  "mcpServers": {
    "sophos-xgs": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sophos-xgs-mcp/dist/index.js"],
      "env": { "SOPHOS_ENABLE_WRITE": "1" }
    }
  }
}

Back this with a restricted API user. The env flag governs what this server offers; it does not limit what the credentials may do. Sophos authenticates the API with ordinary administrator accounts, and their rights come from the assigned administration profile, where every module can be set to None, Read-Only or Read-Write. Use a read-only profile for read-only deployments, and give a write deployment only the modules it actually needs. That boundary holds regardless of bugs in this server.

Updates are read-modify-write

Set operation="update" replaces the entity definition on the appliance. Fields omitted from the request fall back to defaults — they do not stay unchanged. An update meant to flip one flag can silently empty a firewall rule's source and destination networks.

update_entity therefore always fetches the current object, merges your fields onto it, and sends the complete definition. It aborts rather than continuing if:

• the current state cannot be loaded, or the name does not exist
• more than one object matches the identifier
• the object that came back does not carry the field it was addressed by (see below)
• any field present before the update would be missing from what is about to be sent
• after the write, a field changed that was not part of your update

That third condition exists because a filtered Get does not always answer "no such object" by returning nothing. Four entities on an XGS 2100 — SSLVPNPolicy, VPNIPSecConnection, AdminSettings, GatewayConfiguration — answer a Name filter with the element and nothing inside it, because they hold their contents in one record with no top-level Name to filter on. SSLVPNPolicy filtered by name returns literally [{}].

An empty result is not null, so the "does not exist" check passes; merging onto it yields little more than your delta; and the field-loss check has nothing to compare, because the fields were never there. What would reach the appliance is a partial update — against an API that replaces what it updates. For SSLVPNPolicy that is every tunnel policy on the box reduced to a name.

create_entity aborts if the name already exists, delete_entity fetches the object first so you can see what disappears, and preview_write shows the exact XML and field-level diff without sending anything.

To clear a field on purpose, pass null. Omitting it means "leave unchanged".

Confirming every write

This server does not prompt — MCP gives it no mechanism to. In Claude Code you can get a confirmation per write with a PreToolUse hook matching mcp__sophos-xgs__.* that returns permissionDecision: "ask" for the write tools. ask outranks the permission allowlist, so it keeps asking even after "don't ask again".

Two things such a guard should do, both learned the hard way:

• Name the target appliance in the dialog. switch_profile persists across

sessions, so without the hostname a change gets confirmed for one firewall and applied to another.

• Allowlist the read tools rather than denylisting the write tools. A tool added

to a later version then lands on the safe side by default.

The design, including the guard's decision matrix, is written up in docs/superpowers/specs/2026-08-04-write-support-design.md.

Security

• Read-only by default — write tools are absent without SOPHOS_ENABLE_WRITE=1
• Secrets are redacted — Password, PasswordHash, PreSharedKey and similar

fields are masked before results leave the server, and writing a redaction placeholder back to the appliance is refused

• No raw XML from callers — tag names are validated against

^[A-Za-z][A-Za-z0-9_]*$ and every value is escaped

• No hardcoded credentials — loaded from ~/.config/sophos-xgs/ or env vars
• Error sanitization — credentials are stripped from error messages
• TLS — all connections use HTTPS; the self-signed cert bypass is scoped to the

Sophos connection only

Development

pnpm build   # tsc
pnpm test    # node --test
pnpm dev     # run from source

License

AGPL-3.0-only — see LICENSE