websupport-mcp

An MCP server (TypeScript, ESM, stdio) wrapping the Websupport REST API v1 + v2 — DNS, FTP, hosting, databases, mailboxes, VPS and invoices — exposed as MCP tools with signed HMAC-SHA1 authentication.

Status: early. All 50 tools are implemented and published, but most have been verified only as far as reaching the API — routes, signing and error handling are proven; response shapes largely are not. Read docs/verification-matrix.md before relying on any tool, and see IMPLEMENTATION_PLAN.md for progress.

Risk tiers

Tools are registered in three tiers, and the tier gates registration — a read-only deployment never sees a write tool in tools/list at all, so it costs no client context and offers no affordance.

A tool is destructive when it destroys state you cannot cheaply recreate — not merely because it writes. A graceful VPS reboot is write; a hard power-cycle is destructive, because it can corrupt in-flight writes. Taking a snapshot is write; restoring one is destructive, because it discards everything since.

The two opt-ins are independent: WEBSUPPORT_ALLOW_DESTRUCTIVE=1 alone does not unlock write tools, and vice versa.

The confirm: true argument, not MCP elicitation, is the safety boundary. Protocol negotiation may settle well below the revision that supports elicitation — this server's SDK currently tops out at 2025-11-25 — and a gate that disappears against an older client is not a gate.

Install

Requires Node >= 22. Nothing to install ahead of time — npx fetches the package on first run.

Add this to your MCP client's configuration:

{
  "mcpServers": {
    "websupport": {
      "command": "npx",
      "args": ["-y", "websupport-mcp"],
      "env": {
        "WEBSUPPORT_API_KEY": "…",
        "WEBSUPPORT_API_SECRET": "…"
      }
    }
  }
}

That gives you the 30 read-only tools. Nothing in that configuration can change your account.

To allow changes, add only the opt-ins you need — see Risk tiers above:

"env": {
  "WEBSUPPORT_API_KEY": "…",
  "WEBSUPPORT_API_SECRET": "…",
  "WEBSUPPORT_ALLOW_WRITE": "1",
  "WEBSUPPORT_ALLOW_DESTRUCTIVE": "1"
}

Ready-made configurations for each combination live in examples/mcp-config/. Pin a version with websupport-mcp@0.1.1 in place of websupport-mcp.

Once it is wired up, ask your client to run ws_auth_check. It returns {"verified": true} when the credentials work, which is the quickest way to separate a bad key from anything else.

Docker

A Dockerfile is included, for hosts that run containers rather than npx and for registry build sandboxes:

docker build -t websupport-mcp .
docker run -i --rm -e WEBSUPPORT_API_KEY -e WEBSUPPORT_API_SECRET websupport-mcp

-i is not optional — the transport is stdio. No credentials are baked into the image; pass them per run.

From a local checkout

For development, or to run unreleased changes:

npm install
npm run build

Then point command at node and args at the built entrypoint (<checkout>/dist/index.js) instead of npx.

Credentials

Generate a Standard API access pair in WebAdmin (Security → API keys). A DynDNS-only pair authenticates against /nic/update and nothing else.

Copy .env.example for local development. .env is gitignored.

Missing credentials do not stop the server. It starts, registers its tools and answers tools/list unauthenticated — which is what registry build sandboxes, MCP Inspector and client config probes do before anyone holds a key — and the first tool call then fails with a message naming the variable that is absent.

Markets

Websupport is a regional team.blue/Loopia brand, so the API host selects the market. The same application serves every host — GET /v2/docs/openapi.json is byte-identical across all of them — so switching markets is configuration, never a code change.

An unrecognised host warns to stderr and is used anyway, so a newly added market works without waiting for a release.

Documentation

Scope

Order creation and invoice/order payment endpoints are deliberately out of scope and are asserted absent by test. v1 DNS-record CRUD and v1 FTP-account CRUD are deprecated upstream and are not exposed — the v2 tools cover both.

Development

npm test              # offline suite
npm run test:network  # live, unauthenticated probes (market hosts + OpenAPI drift)
npm run typecheck
npm run lint
npm run build

Network suites are separated deliberately: a Websupport outage must not fail the build.

Toolchain

Node >= 22, to run or to build. Node 20 reached end of life on 2026-04-30 and is not supported. CI covers the two live LTS lines, 22 and 24, and builds and smoke-tests the bundle on each.

Building also needs npm >= 11: npm 10 cannot resolve the bundler's dependency tree and fails with an unhelpful Cannot read properties of null (reading 'edgesOut'). If you hit that, upgrade npm rather than debugging the repository.

Security

The credentials this server holds grant full control of a Websupport account — there is no read-only API pair. SECURITY.md covers how they are handled, which tools return sensitive data, and how to report a vulnerability privately.

Contributing

See CONTRIBUTING.md. Note two boundaries enforced by test rather than review: no order or payment endpoints, and every destructive tool must declare confirm: true.

Licence

MIT — see LICENSE.