Namecheap DNS API Landscape & Requirements

Why Namecheap?

• Popular, affordable domain registrar with a documented API.


• Provides full DNS management (records, nameservers, zone configuration).


• Suitable for small-to-medium zones and automation tasks.


• API accessible over HTTPS; no SDK required for basic usage.

Overview of Namecheap DNS API

Authentication parameters (POST body, `application/x-www-form-urlencoded`):

• `ApiUser` - your API username (often same as Namecheap account username)


• `ApiKey` - secret API key (generated in dashboard)


• `UserName` - Namecheap account username (often same as ApiUser)


• `ClientIp` - IP address of the caller; must match whitelisted IPs in Namecheap security settings.


• `Command` - the operation, e.g., `dnsns.getList`, `dnsns.setHostRecords`, etc.

Key Endpoints

| Command | Purpose | Important Parameters | Returns |
|---------|---------|----------------------|---------|
| `dnsns.getList` | List all DNS records for a domain | `SLD` (second-level domain, e.g., `example`), `TLD` (e.g., `com`) | `<DNSHostRecord>` elements with `ID`, `Type`, `Name`, `Value`, `TTL`, `MXPref` (for MX) |
| `dnsns.setHostRecords` | Replace all records for a domain (overwrite) | `SLD`, `TLD`, plus multiple `DNSHostRecord` groups (Type, Name, Value, TTL) | Updated record set |
| `dnsns.addHost` | Add a single record | `SLD`, `TLD`, `RecordType`, `HostName`, `Value`, `TTL`; for MX also `MXPref` | New record ID |
| `dnsns.delHost` | Delete a record | `SLD`, `TLD`, `RecordType`, `HostName`, `Value` (optional?) - usually you need `RecordID`? Actually `delHost` can accept `RecordID` or `HostName`+`Type`+`Value`. Best by `RecordID`. | Success/failure |
| `dnsns.setNameservers` | Change domain nameservers | `SLD`, `TLD`, `Nameserver` (multiple) | Updated nameservers |
| `dnsns.getNameservers` | Get current nameservers | `SLD`, `TLD` | `<Nameserver>` list |

Notes:

• For `dnsns.getList`, records include `ID` (unique per record), which is needed for precise deletion (`dnsns.delHost` can also use `RecordID`). However, some calls use `RecordID` param directly; check docs.


• TTL values: Namecheap accepts `60` (1 min), `1800` (30 min), `3600` (1 hr), etc. There's also "Minimum" and "Default" but best to specify explicit integer.


• `HostName` for records is relative to zone apex (e.g., `www` for `www.example.com`). For root records, use `@` or empty? In Namecheap API, `HostName` is often `"@"` for apex. Need to verify.


• MX records: `MXPref` is integer priority. The `Value` is the mail server hostname (e.g., `mail.example.com.`). We should handle trailing dot? API may accept with or without trailing dot; better to strip/add as needed.


• API keys are long-lived; rotate if compromised.


• IP whitelist: In Namecheap dashboard → Security → API Access → "Allowed IPs". Set to VPS IP (`51.255.200.100`) or dynamic if home IP changes. For MCP server running on VPS, whitelist that IP.

Obtaining API Credentials

1. Log into your Namecheap account.
2. Go to Security → API Access (or directly: https://ap.www.namecheap.com/settings/token/)
3. Generate a new API key:

• Enter a label (e.g., "MCP Server").


• Optionally restrict allowed IPs to your server’s public IP (recommended).


• Click Generate.

• API User – usually your Namecheap username (or a dedicated API username if you created one).


• API Key – the secret string generated.


• UserName – typically the same as API User.

• Sign up at https://www.namecheap.com/sandbox/


• Separate sandbox credentials are provided (different API user/key and test domains).


• Sandbox base URL: `https://api.sandbox.namecheap.com/xml.response`

Requirements for MCP Server

Functional

• Authentication: Read credentials from environment (`NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY`, `NAMECHEAP_USER_NAME`, optionally `NAMECHEAP_CLIENT_IP`). Do not require interactive login.


• Tools:


• `namecheap.domains.list() → [{domain, status?}]`


• `namecheap.dns.list_records(domain) → [{id, name, type, value, ttl, mxpref?}]`


• `namecheap.dns.add_record(domain, name, type, value, ttl?) → {record_id}`


• `namecheap.dns.delete_record(domain, record_id?)` OR `namecheap.dns.delete_record_by(domain, name, type, value?)`


• `namecheap.dns.update_record(record_id, new_value?, new_ttl?) → {updated}`


• `namecheap.dns.set_nameservers(domain, ns_array) → {changed}`


• `namecheap.dns.get_nameservers(domain) → {ns_list}`


• Idempotency: `add_record` should be safe to call repeatedly; if record exists, return existing ID or success.


• Error handling: Convert Namecheap XML errors into descriptive MCP error messages (include error number and text).


• Logging: Minimal, but log failed attempts without exposing credentials.

Non-Functional

• Language: Go (static binary, easy deployment).


• Transport: stdio (JSON-RPC 2.0).


• Security: stdio limits access; optionally require MCP token via env `MCP_SECRET` and reject requests lacking correct `X-MCP-Token` header? Actually stdio doesn't have headers; token can be passed as a parameter to each tool or as part of the `initialize` handshake? Simpler: rely on OS permissions; only authorized user can spawn the binary.


• Performance: Each tool makes one or more HTTPS calls; keep connection efficient (reuse HTTP client).


• Compatibility: Works with any MCP client (e.g., ChatGPT, Claude, custom agents).

Data Model Mapping

xml

<DNSHostRecord>

  <ID>12345</ID>

  <Type>A</Type>

  <Name>www</Name>

  <Value>1.2.3.4</Value>

  <TTL>1800</TTL>

  <MXPref>10</MXPref>  <!-- only for MX -->

</DNSHostRecord>

json

[

  { "id": 12345, "name": "www", "type": "A", "value": "1.2.3.4", "ttl": 1800 }

]

Open Questions

• Should we support adding multiple records in one call? Not needed for MVP.


• Should we support wildcard records? Yes, just pass `*` as name; API supports it.


• Should we support SRV records? Defer; more complex parameters.


• How to handle `HostName` for apex: use `"@"` or `""`? Namecheap expects `"@"` for root; some sources say empty string. We'll test; but in code we can map: if name is `""` or `"@"`, send `"@"`.


• How to get domain list? Namecheap does not have a direct "list domains" endpoint in DNS API; there is `domains.getList` in a different API area. For MCP we might only need to manage DNS for domains we already own; we can either require the user to know the domain string or we can call `domains.getList` (requires different auth group?). Actually Namecheap API has `domains.getList` (requires `Command=domains.getList`). That returns domains the user owns. We can include it; it uses the same credentials. So `namecheap.domains.list()` can call that.

Next Steps

1. Confirm exact request/response parameters via Namecheap's official docs or quick manual test (sandbox account? They have a sandbox environment: `https://api.sandbox.namecheap.com/xml.response`). We should use sandbox for development.
2. Draft MCP tool JSON-RPC method definitions.
3. Implement Go HTTP client and XML structs.
4. Write MCP server skeleton.