spaceship-mcp

An MCP server over the Spaceship.dev API, scoped to DNS record management.

Lets an AI agent read and change DNS records through reviewable tool calls with a preview step — instead of clicking around a registrar console.

Why the surface is deliberately small

The Spaceship API exposes around 50 operations. A server that surfaced all of them would hand a connected agent the ability to:

Operation	Effect
`DELETE /v1/domains/{domain}`	delete a domain
`GET /v1/domains/{domain}/transfer/auth-code`	return the EPP auth code — whoever holds it can transfer the domain away
`PUT /v1/domains/{domain}/transfer/lock`	unlock a domain for transfer
`PUT /v1/domains/{domain}/nameservers`	repoint the entire domain
`POST /v1/domains/{domain}`, `/renew`, `/restore`	spend money
`/v1/sellerhub/*`	list your domains for sale
`/v1/hyperlift/*`	scale, restart and rewrite app environment variables

None of that is exposed here. Six tools ship, and there is no code path from this server to the destructive half of the API. If you need those operations, use the console — the blast radius is too large to sit behind a tool call.

Tools

Tool	Writes?	Notes
`list_domains`	no	paginated
`get_domain`	no	status, expiry, nameservers
`list_dns_records`	no	not gated by the allowlist — reading is safe
`add_dns_records`	yes	allowlisted domains only, two-step confirm
`delete_dns_records`	yes	deletes exactly the records passed, never a zone
`get_async_operation`	no	poll a long-running change

Safety model

Four independent layers, strongest first. Note that the strongest one is not code:

1. Scope the API key. Spaceship lets you choose scopes when minting a key. Create this one with DNS scopes only. If the key cannot delete a domain, no bug in this server can either. Nothing below substitutes for this.

2. Domain allowlist. SPACESHIP_ALLOWED_DOMAINS is checked on every write. Unset means writes are disabled entirely — failing closed is the right default for something that can take a site offline.

3. Two-step confirm. Write tools called without confirm: true change nothing. They return a preview:

the exact payload that would be sent
which sensitive record types it touches (MX, NS, CAA, TXT, SOA — the ones that silently break mail or certificate issuance)
the current zone, for comparison

4. force is never sent. The API documents this flag as "turn-off conflicts resolution checker and force zone update" — it disables the server-side check that stops a malformed payload clobbering a live zone. There is no code path here that sets it.

Access to the server itself is separate and also fails closed: with MCP_AUTH_TOKEN unset, every request is rejected rather than serving DNS write tools openly. The bearer comparison is constant-time.

Why HTTP, not stdio

A stdio MCP server only helps a client that can already reach spaceship.dev from its own network. Sandboxed agent environments frequently cannot — egress is often restricted to an allowlist, and the connection fails at the proxy before it reaches the API.

Hosting this over HTTP and registering it as a remote MCP connector means the connection is brokered by the MCP host rather than the agent's sandbox, which is what makes it usable from a restricted environment at all.

Configuration

cp .env.example .env

Variable	Required	Notes
`SPACESHIP_API_KEY`	yes	mint with DNS scopes only
`SPACESHIP_API_SECRET`	yes	paired with the key
`MCP_AUTH_TOKEN`	yes	bearer token clients present; unset = reject all
`SPACESHIP_ALLOWED_DOMAINS`	for writes	comma-separated; unset = writes disabled
`PORT`	no	default `8080`
`SPACESHIP_BASE_URL`	no	default `https://spaceship.dev/api`

Running

npm install
npm run build
npm start

Or containerised:

docker build -t spaceship-mcp .
docker run --rm -p 8080:8080 --env-file .env spaceship-mcp

Health check — reports whether writes are enabled without revealing configuration:

curl -s localhost:8080/health
# {"status":"ok","server":{...},"protocolVersions":[...],"writesEnabled":true}

Usage

Always preview first:

// tools/call → add_dns_records   (no confirm)
{
  "domain": "example.com",
  "records": [
    { "type": "A", "name": "api", "address": "203.0.113.10", "ttl": 3600 }
  ]
}

// → returns, without changing anything
{
  "status": "preview",
  "wouldWrite": [ ... ],
  "sensitiveTypesIncluded": [],
  "currentZone": [ ... ],
  "next": "Re-run with confirm=true to apply."
}

Re-send with "confirm": true to apply.

Record shapes

Records follow the API's discriminated union on type:

Type	Value field
`A`	`address` (IPv4)
`AAAA`	`address` (IPv6)
`CNAME`	`cname`
`MX`	`exchange` + `preference`
`TXT`	`value`
`NS`	`nameserver`

name is the host part only — "@" for the apex. ttl is optional, 60–3600.

Protocol

Streamable HTTP MCP, JSON-RPC 2.0 over POST /. Supported protocol versions: 2025-06-18, 2025-03-26, 2024-11-05 — the client's requested version is echoed back when supported. Old versions are kept deliberately; removing one silently breaks any client pinned to it.

Implemented methods: initialize, notifications/initialized, ping, tools/list, tools/call. Batch requests are rejected explicitly rather than half-supported.

Verified behaviour

Exercised against a locally running instance:

initialize echoes the client's requested protocol version when supported
unauthenticated POST → 401
write to a non-allowlisted domain → refused, naming the allowlist
ttl: 99999 → refused, quoting the offending value
allowlist unset → writesEnabled: false, writes refused

Not verified: any live call against Spaceship. That needs real credentials. Two things a first real call should confirm:

DELETE body shape. The spec sends the record array bare for delete but wrapped as { items: [...] } for save. That asymmetry is implemented as specified, but is the kind of detail that stays wrong until a real request proves otherwise.
Validation depth. type, name and ttl are validated locally; type-specific value fields are not, so an A record missing address fails at the API rather than here.

Neither is a safety hole — the allowlist, confirm step and force omission all sit in front of them.

Licence

MIT