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 [email protected] 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.
