This server lets an agent manage DNS hostnames via MCP tools.
List hostnames: See all hostnames visible to the key, active count, and plan cap.
Get hostname: Retrieve status and certificate mode for one hostname.
Mint hostname: Register a new stable hostname for an IP or platform target, optionally specifying subdomain, domain, and certificate mode.
Repoint hostname: Change a hostname's address or target while keeping the name.
Diagnose hostname: Check nameserver responses, public resolver visibility, and certificate issuance to debug propagation issues.
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., "@DNSMint MCP Server Mint a new hostname for my server"
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.
Most people want the hosted endpoint instead:
https://dnsmint.com/mcp.It needs nothing installed. In Claude or ChatGPT, add the URL as a connector and sign in. In Claude Code, Cursor or VS Code, point them at the URL with an API key. On a server with no browser, use the device flow. The recipe for each is on dnsmint.com/integrations.
This package is the same tools over stdio, for the case where you want the server running as a local subprocess rather than talking to ours.
Lets an agent mint and manage its own hostnames on DNSMint, through the Model Context Protocol.
Every other DNSMint integration assumes a human wrote the config first. This one does not: an agent that has just been given a machine can ask for a name for it, mid-task.
Hosted | This package | |
Install | nothing | Node, and an entry in a config file |
Claude / ChatGPT connectors | yes, via OAuth | no — they cannot spawn a subprocess |
Headless server | yes, via the device flow | yes |
Credential | API key, or an OAuth grant you can revoke from the dashboard | API key in the client's environment |
Tool updates | reach you immediately | when you upgrade the package |
The hosted endpoint is the one that gets improvements first. Use this if you specifically want a local process — an air-gapped setup pointed at a private deployment, or a client that only speaks stdio.
Related MCP server: Cheqd MCP Toolkit
{
"mcpServers": {
"dnsmint": {
"command": "npx",
"args": ["-y", "dnsmint-mcp-server"],
"env": {
"DNSMINT_API_KEY": "dnsm_..."
}
}
}
}The key needs hostnames:read and hostnames:write. Scope it to one domain and the agent reaches nothing else on the account, which is the point of scoping.
Variable | |
| Required. |
|
|
| API base URL. Defaults to |
Tool | |
| Every name the key can see, plus how many are active against the plan's cap. |
| One name's status and certificate mode. |
| Register an address, get a stable name back. |
| The machine moved; the name does not. |
| Why a name is or is not working. |
| Only when |
The hosted endpoint carries the same six, and decides which to offer from what the credential was granted rather than from an environment variable.
A released hostname is tombstoned and never issued again, to anyone, including you. There is no undo.
That is a bad thing to leave within reach of a model deciding to tidy up, so release_hostname is not registered unless you set DNSMINT_ALLOW_RELEASE=true. When it is, the tool takes a confirm argument that must equal the hostname exactly, checked against the id before anything happens — so a name cannot be released by guessing an id or half-remembering a name.
If the goal is to stop serving, repoint the name or stop the machine. Releasing is for names that are genuinely finished with.
The descriptions are the interface a model actually reads, so they state the rules the API enforces rather than leaving a model to discover them by being refused:
A hostname is one label above a domain. Names below a hostname are not hostnames.
The address class is fixed for life. Public stays public, private stays private; crossing is refused, because one name resolving public then private is how DNS rebinding works.
A newly minted name is pending and goes live within about a minute.
The API does not say where a name points. DNS is the authoritative answer, which is what diagnose_hostname reports.
npm install
npm run buildSomething not working, or a case this does not cover? Open an issue here, or write to hello@dnsmint.com. This server is maintained by the DNSMint team.
Why a hostname is or is not working: what the nameservers answer, what public resolvers see, and whether a certificate has been issued. Use this before assuming something is broken; a name minted moments ago may simply not have propagated.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The hostname's id, from list_hostnames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the description adds valuable context about what the tool inspects (nameserver answers, public resolver views, certificate issuance). It clarifies the diagnostic nature without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first explains the diagnostic output, the second gives usage advice. No filler; all information is relevant and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only diagnostic tool with annotations covering safety, the description sufficiently explains what it does and when to use it. It could mention the output format, but that's not critical given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id parameter described as the hostname's id from list_hostnames. The tool description doesn't add additional parameter details beyond that, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it diagnoses why a hostname is or isn't working by checking nameservers, public resolvers, and certificate issuance. It differentiates from siblings like list_hostnames (listing), get_hostname (retrieving details), mint_hostname (creation), and repoint_hostname (modification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It advises using this tool before assuming a hostname is broken, and notes that a recently minted name may not have propagated yet. This provides clear context for when to use it, though it doesn't explicitly exclude alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One hostname's status and certificate mode. Does not say where it points: DNS is the authoritative answer for that, so use diagnose_hostname or resolve the name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The hostname's id, from list_hostnames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to restate that. The description adds valuable behavioral context by disclosing a limitation: it does not reveal DNS resolution, and directs to diagnose_hostname. This goes beyond the annotation and helps the agent set expectations. It doesn't cover error behavior or return format, but for a read-only getter this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The primary purpose is front-loaded, and the limitation and alternative are placed second, so an agent scanning quickly gets the key information immediately. No redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, no output schema, and readOnlyHint annotation, the description covers what the tool returns (status, cert mode), what it doesn't (DNS), and the alternative path. Nothing essential is missing for an agent to decide whether to call it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter id with a clear source ('from list_hostnames'), and schema coverage is 100%. The description adds no additional meaning about the parameter itself, only about the tool's output scope. Per the rubric, baseline 3 applies when schema covers parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it retrieves a single hostname's status and certificate mode. It also differentiates from siblings by explicitly noting what it does NOT provide (where it points) and naming the alternative tool, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance for when to use an alternative: if you need to know where the hostname points, use diagnose_hostname or resolve the name. It implies this tool is for status and certificate mode, and the sibling list_hostnames is for listing all, though it doesn't explicitly state 'use list_hostnames for multiple' or 'use this for a single hostname'. The guidance is clear enough for the common case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every hostname this key can see, with how many are active and the plan's cap. Check the cap before minting: a hostname is the unit the plan counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that it returns active counts and plan cap, which is behavioral context beyond annotations. However, it doesn't specify details like pagination, sorting, or the exact meaning of 'active', leaving some gaps. Given the annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the core purpose and output, the second gives a usage hint. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with no parameters and no output schema, the description covers the key aspects: what is returned (hostnames, active count, cap) and why it should be used (before minting). Minor gaps like pagination or ordering are not critical given the simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is effectively 100% (vacuously). There is nothing for the description to add about parameters, and the baseline for 0-parameter tools is 4. The description doesn't mention parameters, which is fine.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all hostnames visible to the current key, along with active counts and plan cap. It explicitly differentiates itself from siblings like mint_hostname (creates) and get_hostname (retrieves a single hostname) by indicating a full listing and capacity overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Check the cap before minting'. It implies this tool should be called before creating a new hostname to verify capacity. It doesn't explicitly name alternatives or when not to use it, but the context is clear enough for an agent to know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register an address and get back a stable hostname that survives the address changing. This is the tool to use when a machine or agent needs a name.
The address class is fixed for the life of the name: mint with a public address and it stays public, mint with a private one and it stays private. Crossing later is refused, so pass the address the machine will actually serve on.
A hostname is one label above a domain. Names below a hostname are not hostnames and cannot be minted.
Newly minted names report status 'pending' and go 'live' within about a minute.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | No | IPv4 or IPv6, public or private. One of ip or target is required. | |
| domain | No | Which of the account's domains to mint on. Omitted, DNSMint picks when the account holds one. | |
| target | No | A platform endpoint to follow instead of a fixed address, when the platform gave you a URL and no IP. DNSMint resolves it and serves ordinary A and AAAA records. | |
| subdomain | No | The label to use. Omitted, DNSMint picks an opaque one. | |
| certificate | No | Who holds the private key. 'self' (default) means you run an ACME client. 'managed' means DNSMint gets and renews the certificate and you fetch it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, idempotentHint=false), so the description carries the full burden. It discloses that the address class is fixed and crossing later is refused, that newly minted names go 'pending' then 'live' within a minute, and that DNSMint may auto-pick domain/subdomain or resolve target URLs. This is rich behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into short, purposeful paragraphs. It front-loads the core purpose, then provides usage context, behavioral constraints, and lifecycle information. Every sentence contributes meaning, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema), the description covers the essential aspects: what it does, when to use it, key constraints, and lifecycle. It doesn't explicitly describe the response format beyond implying a hostname is returned, but since no output schema exists and the description mentions 'get back a stable hostname,' it is reasonably complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described, so baseline is 3. The description adds meaningful guidance not in the schema, such as 'pass the address the machine will actually serve on' (ip) and the fixed address class implication. However, most parameter specifics (omitted domain picks, subdomain opaque, certificate types) are already in the schema, so the incremental value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Register an address and get back a stable hostname that survives the address changing.' It specifies the resource (hostname) and the purpose (naming a machine or agent). It distinguishes from siblings by focusing on creation (mint) versus management (list, get, repoint, diagnose), even though it doesn't name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: 'This is the tool to use when a machine or agent needs a name.' It also provides constraints like 'pass the address the machine will actually serve on' and clarifies that names below a hostname cannot be minted. However, it does not explicitly mention alternatives or when not to use it, so it misses the full 'when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Point an existing hostname at a new address. This is what makes the name worth having: the machine moves, the name does not, and everything holding the URL keeps working.
Repointing within an address class is free, including between IPv4 and IPv6. Crossing between public and private is refused, because one name resolving public then private is how DNS rebinding works.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The hostname's id, from list_hostnames. | |
| ip | No | The new address. | |
| target | No | A platform endpoint to follow instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true. The description adds meaningful non-obvious behavior: IPv4/IPv6 changes are allowed but public/private crossings are refused due to DNS rebinding. This gives agents the key failure cases without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The action is front-loaded and the whole description is about three short sentences. The motivational line about the machine moving is slightly non-essential for invoking the tool, but it is brief and reinforces the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with three parameters, no output schema, and annotations covering idempotency, the description plus the fully described schema is sufficient to select and invoke it. It could clarify whether exactly one of ip/target is required and what the response looks like, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by constraining the ip parameter (IPv4/IPv6 changes are permitted; public/private crossing is not), which is absent from the schema's simple 'The new address.' description. The target parameter is only covered by the schema, but its 'instead' wording is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb + resource: 'Point an existing hostname at a new address.' It clearly identifies this as the update operation for existing hostnames, distinguishing it from the sibling list/get/mint/diagnose tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: repointing applies to an existing hostname, and address-class rules are stated explicitly ('Repointing within an address class is free... Crossing between public and private is refused'). It does not explicitly name sibling alternatives or state when-not-to-use, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0diagnose_hostnameget_hostnamelist_hostnamesmint_hostnamerepoint_hostnameScored across 5 tools
Each tool targets a distinct operation: listing, single-status lookup, minting, repointing, and diagnosis. get_hostname and diagnose_hostname are explicitly differentiated, with diagnose reserved for DNS/certificate troubleshooting.
All five tools use a consistent verb_noun pattern with snake_case (list_hostnames, get_hostname, mint_hostname, repoint_hostname, diagnose_hostname). Pluralization of list_hostnames is natural and does not break the pattern.
Five tools is well-scoped for a focused DNS hostname minting service. Each tool covers an essential operation without redundancy or bloat.
The set covers create (mint), read (list/get), update (repoint), and diagnosis, but has no delete, retire, or deprecate operation for hostnames. This is a notable lifecycle gap that prevents cleanup of unwanted names.
Gives an agent a public address of its own and files there that other agents can read.
Connect AI agents to Replynodes over the Model Context Protocol.
Mint a secure HTTPS endpoint for your agents. Each on its own dedicated domain.
Agent-first domain registration and DNS management, paid with USDC via x402.
