← Back to project

Namecheap DNS MCP Architecture & Tool Specification



This report details the architecture for an MCP server that provides Namecheap DNS management capabilities. It defines the component layout, MCP tool signatures, and data mappings.

---

Architecture Overview



The system consists of a single Go binary that:




+---------------------+      JSON-RPC      +-------------------+

| MCP Client (e.g.,   | <----------------->|   Namecheap MCP   |

| ChatGPT, CLI)       |                    |   Server (Go)     |

+---------------------+                    +-------------------+

                                                     |

                                                     | HTTPS POST (form)

                                                     v

                                          +----------------------+

                                          | Namecheap DNS API    |

                                          | (xml.response)       |

                                          +----------------------+


---

Environment Variables



Transport Modes



Stdio Mode (Primary)



Web Mode (Secondary)


bash

  namecheap-mcp --web --port 8080 --token=secret

Then from a browser or script:
bash

  curl -X POST http://localhost:8080/mcp \

    -H "Authorization: Bearer secret" \

    -d '{"jsonrpc":"2.0","method":"namecheap.domains.list","id":1}'


---

MCP Tool Definitions



All tools follow JSON‑RPC 2.0 with named parameters. They return a result object or an error.

1. namecheap.domains.list



List domains the account can manage.

Params: none

Result: `{ "domains": [ { "name": "example.com", "status": "Active" } … ] }`

Implementation: Calls `domains.getList` (Namecheap API). Parse `<Domain>` elements for `Name` and `Status`.

2. namecheap.dns.list_records



List DNS records for a domain.

Params:


Result: `{ "records": [ { "id": int, "name": string, "type": string, "value": string, "ttl": int, "mxpref"?: int } ] }`


Implementation: Calls `dnsns.getList` with `SLD` and `TLD` split from domain. Normalize `HostName` values: apex becomes `"@"`; others as provided. Convert TTL to int. Include `MXPref` only for type MX.

3. namecheap.dns.add_record



Add a new DNS record.

Params:


Result: `{ "record_id": int }`


Implementation:


4. namecheap.dns.delete_record



Delete a DNS record. Two variants possible; we support both by letting caller provide either `record_id` or a combination `(name, type, value)`.

Params:


Result: `{ "deleted": bool }`


Implementation:


5. namecheap.dns.update_record



Update a record’s value and/or TTL.

Params:


Result: `{ "updated": bool }`


Implementation: Namecheap lacks a direct “update” endpoint. Approach:

Actually, Namecheap API has `dnsns.updateHost`? Not documented? Some sources indicate `dnsns.setHostRecords` replaces all, but there might also be `dnsns.editHost` or `dnsns.updateHost`. Checking: The official API includes `dnsns.setHostRecords` (replace), `dnsns.addHost`, `dnsns.delHost`. I recall there is also `dnsns.updateHost`? Let’s verify memory: In older API there is `dnsns.setHostRecords` (replace entire set) and `dnsns.addHost`/`delHost`. To update a single record, the common pattern is:
That’s atomic but requires sending all records. Simpler for MVP: we could disallow per‑record update and instead require delete + add. But user experience is nicer with `update_record`. Even if we implement update as delete+add in one operation (with careful ordering), we risk race conditions if records change concurrently. However, for an automation agent, it’s probably fine. Safer: implement `update_record` by calling `dnsns.setHostRecords` with the full zone after modifying that one record. That is a consistent replace. For small zones (<500 records) it’s acceptable.
Alternatively, we can try `dnsns.editHost` if it exists; but not in common docs. I’ll assume `setHostRecords` is the only way. So `update_record` will:
This replaces the entire zone, so we must be careful not to lose other records. We’ll include every other record unchanged.
Complexity: moderate. For MVP we could skip `update_record` and rely on `delete_record` + `add_record`. Simpler. We’ll decide later.


Proposed simplification: Do not implement `update_record` in MVP. Use `delete_record` and `add_record` instead.

6. namecheap.dns.set_nameservers



Set custom nameservers for a domain.

Params:


Result: `{ "changed": bool }`


Implementation: Call `dnsns.setNameservers` with `SLD`, `TLD`, and multiple `Nameserver` params.

7. namecheap.dns.get_nameservers



Get current nameservers for a domain.

Params:


Result: `{ "nameservers": [string] }`


Implementation: Call `dnsns.getNameservers`.

---

Error Handling



All Namecheap API errors return `<Errors><Error><Number>` and `<Text>`. We will map to MCP error objects with `code` and `message`.

Expected error codes (from Namecheap docs):


We’ll forward the error number and text in the MCP error response. Tools should return `null` result on error and include an error object.


---

Rate Limiting & Retries



Namecheap does not document strict rate limits, but we should:


---


Security Considerations



---


Testing Strategy



---


Implementation Effort



---


Word count: ~1,150