Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Tophost DNS MCP List the DNS records for my domain example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the unofficial Tophost DNS API.
This project is unofficial and is not affiliated with, endorsed by, or supported by Tophost.
The server exposes the DNS operations implemented by tophost-dns-api as
Model Context Protocol tools. It does not talk to the Tophost control panel
directly.
MCP client / AI agent
|
v
Tophost DNS MCP
|
v
Tophost DNS API
|
v
TophostThe separation is intentional: Tophost authentication, trusted 2FA, product
discovery, HTML parsing and DNS protocol details remain inside
tophost-dns-api. This repository is only the MCP tool layer.
Initial implementation. The package targets the current stable v2 line of the official Python MCP SDK.
Related MCP server: Spaceship MCP Server
Python 3.11 or newer
a running tophost-dns-api instance
the API key configured by that instance
git clone https://github.com/DanielVd/tophost-dns-mcp.git
cd tophost-dns-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e .For development:
pip install -e '.[dev]'export TOPHOST_DNS_API_URL=http://127.0.0.1:8765
export TOPHOST_API_KEY='replace-me'Optional:
export TOPHOST_MCP_REQUEST_TIMEOUT=20The MCP process does not need TOPHOST_USER, TOPHOST_PASS, OTP values or
trusted 2FA state. Those remain configured only in tophost-dns-api.
The default transport is stdio:
tophost-dns-mcpFor Streamable HTTP:
tophost-dns-mcp \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000The MCP endpoint is the SDK default, /mcp.
For development with the MCP Inspector:
mcp dev src/tophost_dns_mcp/server.py:mcpTool | Mutation | Purpose |
| no | Check REST API reachability |
| no | List domains available to the account |
| no | List/filter DNS records |
| no | Read one record by current record ID |
| yes | Create a record; identical records are a no-op |
| yes | Update with mandatory expected-state guards |
| yes | Delete with mandatory expected-state guards |
Read-only and mutation tools include MCP tool annotations. These annotations are client hints only; they are not treated as an authorization mechanism.
The MCP layer deliberately makes update and delete stricter than the REST API.
Before updating or deleting a record, first read it and pass both
expected_value and expected_priority back to the mutation tool. The REST
API verifies that the record has not changed in the meantime and refuses a stale
mutation.
The underlying API can change a Tophost record ID after an update. Always use the ID returned in the mutation result for subsequent operations.
REST API application errors are converted into MCP tool errors with the stable
error code and message returned by tophost-dns-api.
Raw HTML, response bodies, API keys and authentication material are not included in tool errors.
ruff check src tests
pytest -qREST API and Tophost protocol implementation:
https://github.com/DanielVd/tophost-dns-api
MIT. See LICENSE.
Create a DNS record. The underlying API treats an already-identical record as a no-op.
Inputs: name (required), value (required), domain (required), record_type (required), +1 more. Returns: after, before, changed, message, +1 more
Delete a DNS record using mandatory expected_value and expected_priority optimistic-concurrency guards. Read the record first and pass the observed state.
Inputs: domain (required), record_id (required), expected_value (required), expected_priority (required). Returns: after, before, changed, message, +1 more
Read one DNS record by its current Tophost record ID.
Inputs: domain (required), record_id (required). Returns: id, name, type, value, +1 more
List DNS records for one Tophost domain. Optional name, type and value filters can be combined.
Inputs: domain (required), name, value, record_type. Returns: result
List domains discovered by the authenticated Tophost DNS API account.
Inputs: no named parameters. Returns: result
Check whether the configured Tophost DNS REST API process is reachable.
Inputs: no named parameters. Returns: status
Update a DNS record using expected_value and expected_priority as mandatory optimistic-concurrency guards. Read the record first and pass the observed state.
Inputs: domain (required), record_id (required), expected_value (required), expected_priority (required), +2 more. Returns: after, before, changed, message, +1 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Each tool targets a distinct action: health check, listing domains, listing/reading records, and create/update/delete operations. There is no overlap between list and get-by-ID, and update/delete are clearly separated by their optimistic-concurrency guards.
Most tools follow a clear verb_noun snake_case pattern (list/get/create/update/delete). The health check tool uses a noun-style name with a vendor prefix, which is a minor deviation, but it does not create confusion.
Seven tools is a well-scoped size for a DNS record management server: one health check, one domain enumeration tool, and a full record lifecycle. No tool feels redundant or superfluous.
The set covers the core DNS record lifecycle completely (list, get, create, update, delete) plus domain discovery and API health. There are no obvious missing operations for the stated purpose.
29 DNS, SEO, SSL, security, WHOIS & mail tools for AI agents. Pay per call (x402) or card API key.
Register, transfer and manage domain names and DNS from your AI agent.
Custom domains for SaaS and AI agents: search, register, connect DNS, and issue HTTPS over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
