MCP

Agents speak MCP over stateless Streamable HTTP. Same Bearer key as the JSON API. Cookie sessions are rejected.

Mint a key <JSON API>

POST /api/v1/mcp

Transport HTTP stateless, JSON responses

Auth gdk_ Bearer only

Scope key domain + read/write

Endpoint

POST /api/v1/mcp on this origin (and onion / I2P). No extra ports. The JSON API at /api is REST; this is MCP. Domain scope and read/write on the key apply the same way.

URL

https://goydns.com/api/v1/mcp

Protocol

JSON-RPC 2.0 over Streamable HTTP. The server is stateless and replies with JSON. IDEs still send initialize; you can POST tools/call alone. Send Accept: application/json, text/event-stream if a client library requires it.

initialize

shell

curl -sS -H "Authorization: Bearer gdk_…" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"0\"}}}" \
  https://goydns.com/api/v1/mcp

tools/call

shell

curl -sS -H "Authorization: Bearer gdk_…" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"list_zones\",\"arguments\":{}}}" \
  https://goydns.com/api/v1/mcp

Add to an IDE

Create a key in Settings first. These links use a placeholder until then.

Cursor, VS Code, and Insiders open the app. Other IDEs get a copy-paste snippet.

Cursor VS Code Insiders

Claude Code

claude mcp add --transport http goydns https://goydns.com/api/v1/mcp --header "Authorization: Bearer gdk_…"

Cursor mcp.json

{
  "mcpServers": {
    "goydns": {
      "url": "https://goydns.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer gdk_…"
      }
    }
  }
}

Windsurf (serverUrl)

{
  "mcpServers": {
    "goydns": {
      "serverUrl": "https://goydns.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer gdk_…"
      }
    }
  }
}

Zed context_servers

{
  "context_servers": {
    "goydns": {
      "url": "https://goydns.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer gdk_…"
      }
    }
  }
}

Claude Desktop: Settings → Connectors → custom connector.

URL

https://goydns.com/api/v1/mcp

Header

Authorization: Bearer gdk_…

Tools

Ask an agent to list your domains, add an A at www, or preview a BIND paste. Tool names still say zone; that is one hosted domain.

Tool	Arguments	Notes
list_zones	-	Domains visible to this key
add_zone	{ zone }	Bearer cannot add domains; returns forbidden. Use the dashboard.
delete_zone	{ zone, confirm }	confirm must equal the domain. Bearer cannot delete domains.
get_zone	{ zone }	Records, NS status, CDS, DNSSEC
list_records	{ zone }	User records with a human summary
add_record	{ zone, owner, type, ttl, data }	write. Host @ is the apex.
replace_record	old_* plus new fields	write. One transaction.
delete_record	{ zone, owner, type, data }	write
import_records	{ zone, text, preview, replace }	read may set preview true
replace_zone_text	{ zone, text, preview }	write. BIND text replaces user records. read may preview
export_zone	{ zone, format }	bind, json, or csv body
check_nameservers	{ zone }	Recheck parent NS
check_dnssec	{ zone }	Recheck parent DS vs CDS

No TOTP or API-key tools. Add and delete domains on the dashboard. DNS policy is the same as the JSON API.

Example

prompt

List my GoyDNS domains, then add www A 203.0.113.10 on example.com with TTL 3600.

Auth

Bearer API key from Settings. Cookie sessions return unauthorized.
Inactive accounts get 403 payment required on this endpoint.
Read keys cannot mutate; they can preview imports and recheck nameservers.

GoyDNS