# xyz.frl - Comprehensive Dynamic DNS & Remote MCP Technical Reference

## 1. Service Specification
- Service: Stateless Dynamic DNS & Remote Model Context Protocol Service
- Production Domain: xyz.frl
- Protocol Transports:
- REST API: HTTPS at `https://xyz.frl/`
- Remote MCP (Streamable HTTP): `https://xyz.frl/mcp`
- Remote MCP (SSE): `https://xyz.frl/mcp/sse`
- Remote MCP (HTTP POST): `https://xyz.frl/mcp/message`
- Protocol Versions: `2024-11-05`, `2025-11-25`, and `2026-07-28`
- Authentication: Stateless cryptographic HMAC token verification
- Registration Requirement: None (zero sign-up, zero accounts, zero API keys)

## 2. REST API Endpoints

### 2.1 GET /generate
Provisions a new dynamic hostname and cryptographic password.
- Request: `GET https://xyz.frl/generate`
- Rate Limit: 1 request per minute per IP
- Success Response (200 OK):
```json
{
"hostname": "<uuid32>.xyz.frl",
"username": "<uuid32>",
"password": "<base64_hmac>"
}
```

### 2.2 GET /nic/update
Standard DynDNS v2 compatible record update endpoint.
- Request: `GET https://xyz.frl/nic/update?hostname=<hostname>&myip=<ip>`
- Authentication: HTTP Basic Auth (`username` = 32-hex UUID, `password` = cryptographic token)
- Parameters:
- `hostname` (optional): FQDN to update
- `myip` (optional): IPv4 or IPv6 address (comma-separated for dual-stack). If omitted, caller public IP is auto-detected.
- Success Response: HTTP 202 Accepted (`Update queued`)

## 3. Remote Model Context Protocol (MCP)
- Specification: Model Context Protocol (modelcontextprotocol.io)
- Protocol Versions: `2024-11-05` (lifecycle handshake), `2025-11-25`, and `2026-07-28` (stateless Streamable HTTP & `server/discover`)
- Transports:
- Streamable HTTP: `https://xyz.frl/mcp` (direct POST with `Content-Type: application/json`)
- Server-Sent Events (SSE): `https://xyz.frl/mcp/sse` (streaming handshake and event channel)
- SSE Message Dispatch: `https://xyz.frl/mcp/message`

### 3.1 Tools Catalog
1. `generate_hostname`: Provision new credentials (`hostname`, `username`, `password`).
2. `update_dns`: Synchronize DNS A/AAAA records with optional explicit or auto-detected IP.
3. `get_caller_ip`: Query caller public WAN IP and IP family.
4. `check_health`: Query operational status.

### 3.2 Developer Environments & Agent CLIs

#### Antigravity by Google DeepMind (`~/.gemini/config/mcp_config.json` or `.agents/mcp_config.json`):
```json
{
"mcpServers": {
"xyz.frl": {
"url": "https://xyz.frl/mcp"
}
}
}
```

#### Claude Code CLI:
```bash
# Add remote MCP tool endpoint to Claude Code
claude mcp add --transport http xyz.frl https://xyz.frl/mcp
```

#### Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"xyz.frl": {
"url": "https://xyz.frl/mcp/sse"
}
}
}
```

#### Cursor (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"xyz.frl": {
"url": "https://xyz.frl/mcp/sse"
}
}
}
```

#### Codeium Windsurf (`~/.codeium/windsurf/mcp_config.json`):
```json
{
"mcpServers": {
"xyz.frl": {
"serverUrl": "https://xyz.frl/mcp/sse"
}
}
}
```

#### Cline / Roo Code (`cline_mcp_settings.json`):
```json
{
"mcpServers": {
"xyz.frl": {
"type": "streamableHttp",
"url": "https://xyz.frl/mcp"
}
}
}
```

#### Block Goose (`~/.config/goose/config.yaml`):
```yaml
extensions:
xyz.frl:
name: "xyz.frl Dynamic DNS"
type: streamable_http
uri: "https://xyz.frl/mcp"
enabled: true
```

#### Continue.dev (`~/.continue/config.yaml`):
```yaml
mcpServers:
- name: xyz.frl
type: sse
url: https://xyz.frl/mcp/sse
```

#### Zed Editor (`settings.json`):
```json
{
"context_servers": {
"xyz.frl": {
"url": "https://xyz.frl/mcp/sse"
}
}
}
```

### 3.3 Autonomous Agent Framework Integrations

#### Pydantic AI (`pydantic-ai`)
```python
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPToolset

# Connect via Streamable HTTP
mcp_toolset = MCPToolset("https://xyz.frl/mcp")
agent = Agent("openai:gpt-4o", toolsets=[mcp_toolset])
result = agent.run_sync("Provision dynamic DNS hostname and check health.")
print(result.data)
```

#### LangGraph / LangChain (`langchain-mcp-adapters`)
```python
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

async def main():
async with MultiServerMCPClient({
"xyz.frl": {
"url": "https://xyz.frl/mcp/sse",
"transport": "sse",
}
}) as client:
model = ChatOpenAI(model="gpt-4o", temperature=0)
agent = create_react_agent(model, client.get_tools())
result = await agent.ainvoke({
"messages": [("user", "Provision a dynamic hostname and bind it to my IP.")]
})
print(result["messages"][-1].content)

asyncio.run(main())
```

#### Hugging Face `smolagents`
```python
from smolagents import MCPClient, CodeAgent, HfApiModel

with MCPClient([{"url": "https://xyz.frl/mcp/sse"}]) as tools:
agent = CodeAgent(tools=tools, model=HfApiModel())
agent.run("Generate a dynamic DNS hostname and check backend health.")
```

#### CrewAI (`crewai`)
```python
from crewai import Agent, Crew, Task
from crewai.mcp import MCPServerSSE

dns_agent = Agent(
role="Infrastructure Agent",
goal="Provision and maintain dynamic DNS records autonomously",
backstory="DevOps agent maintaining live DNS ingress pointers",
mcps=[MCPServerSSE(url="https://xyz.frl/mcp/sse")],
)
task = Task(
description="Provision dynamic hostname and update records.",
expected_output="Registered FQDN and confirmation status.",
agent=dns_agent,
)
Crew(agents=[dns_agent], tasks=[task]).kickoff()
```

#### Microsoft AutoGen 0.4+ (`autogen-agentchat` & `autogen-ext`)
```python
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import SseServerParams, mcp_server_tools

async def main():
params = SseServerParams(url="https://xyz.frl/mcp/sse")
tools = await mcp_server_tools(params)
agent = AssistantAgent(
name="dns_agent",
model_client=OpenAIChatCompletionClient(model="gpt-4o"),
tools=tools,
)
result = await agent.run(task="Query detected IP and generate dynamic hostname.")
print(result.messages[-1].content)

asyncio.run(main())
```

#### LlamaIndex (`llama-index-tools-mcp`)
```python
import asyncio
from llama_index.core.agent import FunctionCallingAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

async def main():
mcp_client = BasicMCPClient("https://xyz.frl/mcp/sse")
tools = McpToolSpec(client=mcp_client).to_tool_list()
agent = FunctionCallingAgent.from_tools(tools=tools, llm=OpenAI(model="gpt-4o"))
print(await agent.achat("Provision a dynamic DNS hostname."))

asyncio.run(main())
```

### 3.4 Direct HTTP JSON-RPC 2.0 / cURL Integration
```bash
# 1. Modern MCP Discovery (Protocol 2026-07-28)
curl -s -X POST https://xyz.frl/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}'

# 2. Call tool generate_hostname via JSON-RPC
curl -s -X POST https://xyz.frl/mcp/message \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_hostname","arguments":{}}}'

# 3. Update DNS record with auto-detected IP
curl -s -X POST https://xyz.frl/mcp/message \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"update_dns","arguments":{"username":"<UUID>","password":"<TOKEN>"}}}'
```

## 4. Architectural Use Cases & Implementation Recipes
Comprehensive guides for specific technical environments and automation patterns:
- [Home Automation & IoT](https://xyz.frl/use-cases/home-automation-iot): Home Assistant configuration.yaml, Raspberry Pi crontab, and IPv6 CGNAT bypass.
- [Remote Server Access & SSH](https://xyz.frl/use-cases/remote-server-access): systemd service and timer units, ~/.ssh/config alias, and fail2ban hardening.
- [Homelab & Self-Hosting](https://xyz.frl/use-cases/homelab-self-hosting): Alpine Docker compose sidecar, pfSense/OPNsense custom DynDNS, and Caddy reverse proxy TLS.
- [WireGuard VPN Endpoints](https://xyz.frl/use-cases/wireguard-vpn): WireGuard endpoint DNS caching caveats, 60s TTL propagation, and client reresolve-dns.sh integration.
- [Security Cameras & NVR](https://xyz.frl/use-cases/security-cameras): Frigate NVR / RTSP streaming setup, WireGuard tunneling, and zero cloud subscriptions.
- [Autonomous AI Agents & MCP](https://xyz.frl/use-cases/ai-agents-mcp): Agent-to-agent communication, ephemeral dynamic hostnames, and automated MCP tool execution.
- [Complete Use Cases Collection](https://xyz.frl/use-cases): Directory index of all technical guides.
