---
name: register-domain
description: Publish your domain's AI capabilities on AgentRoot using DNS TXT records and a manifest. Use when a user wants to register their domain, publish agents/skills/MCP servers, or make their AI capabilities discoverable.
auth: none
cost: free
endpoints:
  - method: POST
    url: https://agentroot.io/api/submit
    description: Submit a domain for DNS verification and indexing
    params:
      domain: The domain to register (required)
---

# Register Domain

Publish your domain's AI capabilities on AgentRoot — the DNS-native open registry for the agentic internet. No API keys, no gatekeepers, just DNS and JSON.

## When to use

- The user wants to register their domain on AgentRoot
- The user wants to publish agents, MCP servers, skills, or A2A endpoints
- The user asks "how do I list my agent/skill in a registry?"
- The user wants to make their AI capabilities discoverable by other agents

## How it works

AgentRoot uses the DNS-first protocol. Registration is a 4-step process:

1. **Create a manifest** — JSON document listing your capabilities
2. **Deploy it** — host at `https://yourdomain.com/.well-known/agentroot.json`
3. **Set a DNS TXT record** — point `_agentroot.yourdomain.com` to the manifest
4. **Submit to the registry** — AgentRoot verifies DNS and indexes your records

## Step 1: Create the manifest

Use the CLI to scaffold a template:

```bash
npx agent-root init --domain yourdomain.com
```

This creates `.well-known/agentroot.json`. Edit it with your records:

```json
{
  "domain": "yourdomain.com",
  "records": [
    {
      "type": "mcp",
      "id": "my-tools",
      "name": "My Tools",
      "description": "MCP server for my API",
      "endpoint": "https://yourdomain.com/mcp",
      "transport": "sse",
      "tools": [
        { "name": "search", "description": "Search our database" }
      ]
    },
    {
      "type": "agent",
      "id": "assistant",
      "name": "My Assistant",
      "description": "AI assistant for our platform",
      "endpoint": "https://yourdomain.com/agent",
      "protocol": "a2a",
      "capabilities": ["search", "analyze"]
    },
    {
      "type": "skill",
      "id": "coding-helpers",
      "name": "Coding Helpers",
      "description": "Skills for working with our SDK",
      "index": "https://yourdomain.com/.agents/skills/index.json"
    }
  ]
}
```

### Record types

| Type | What it declares | Key fields |
|------|-----------------|------------|
| `agent` | AI agent | endpoint, protocol, capabilities |
| `mcp` | MCP server | endpoint, transport, tools |
| `skill` | SKILL.md collection | index, skill_md, or inline skills array |
| `a2a` | Agent-to-Agent endpoint | endpoint, protocol, capabilities |

### Skill records — three formats

Skills can be declared in three ways:

**1. Index URL** — points to a separate skills index JSON:
```json
{ "type": "skill", "id": "my-skills", "name": "My Skills", "index": "https://yourdomain.com/.agents/skills/index.json" }
```

**2. Direct SKILL.md URL** — single skill, URL directly in the record:
```json
{ "type": "skill", "id": "lint-fix", "name": "Lint Fix", "skill_md": "https://yourdomain.com/.agents/skills/lint-fix/SKILL.md" }
```

**3. Inline skills array** — multiple skills embedded in the manifest record:
```json
{ "type": "skill", "id": "helpers", "name": "Helpers", "skills": [
  { "id": "lint-fix", "name": "Lint Fix", "skill_md": "https://yourdomain.com/.agents/skills/lint-fix/SKILL.md" },
  { "id": "test-gen", "name": "Test Gen", "skill_md": "https://yourdomain.com/.agents/skills/test-gen/SKILL.md" }
]}
```

## Step 2: Validate the manifest

```bash
npx agent-root validate .well-known/agentroot.json
```

Fix any errors before proceeding.

## Step 3: Deploy and set DNS

1. Deploy the manifest to `https://yourdomain.com/.well-known/agentroot.json` (must be HTTPS)

2. Add a DNS TXT record:
   ```
   Host:  _agentroot.yourdomain.com
   Type:  TXT
   Value: v=ar1 manifest=https://yourdomain.com/.well-known/agentroot.json
   ```

   **Alternative: inline mode** (for a single record, no manifest needed):
   ```
   Host:  _agentroot.yourdomain.com
   Type:  TXT
   Value: v=ar1 type=mcp name=MyTools endpoint=https://yourdomain.com/mcp transport=sse
   ```

3. DNS propagation takes 1-60 minutes. Verify with:
   ```bash
   npx agent-root resolve yourdomain.com
   ```

## Step 4: Submit to the registry

### Via CLI

```bash
curl -X POST https://agentroot.io/api/submit \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourdomain.com"}'
```

### Via HTTP (WebFetch)

```
POST https://agentroot.io/api/submit
Content-Type: application/json

{ "domain": "yourdomain.com" }
```

### Success response

```json
{
  "success": true,
  "domain": "yourdomain.com",
  "message": "Domain verified and indexed",
  "records_found": 3
}
```

### No records found

```json
{
  "success": false,
  "message": "No _agentroot TXT record found for yourdomain.com",
  "instructions": {
    "record": "_agentroot.yourdomain.com",
    "type": "TXT",
    "value": "v=ar1 manifest=https://yourdomain.com/.well-known/agentroot.json",
    "spec": "https://agentroot.io/docs/protocol"
  }
}
```

## Subdomains

You can register capabilities on subdomains too. Each subdomain gets its own `_agentroot` TXT record:

```
_agentroot.api.yourdomain.com  TXT  "v=ar1 manifest=https://api.yourdomain.com/.well-known/agentroot.json"
```

List subdomains in the parent manifest so resolvers can discover them:

```json
{
  "domain": "yourdomain.com",
  "records": [...],
  "subdomains": ["api", "docs"]
}
```

## Instructions

1. Ask what the user wants to publish — agents, MCP servers, skills, or a combination
2. Run `npx agent-root init --domain <domain>` to scaffold the manifest
3. Help them fill in the records based on what they're publishing
4. Run `npx agent-root validate` to check it
5. Guide them to deploy the manifest and set the DNS TXT record
6. Once DNS is set, use `WebFetch` to POST to `https://agentroot.io/api/submit` with their domain
7. Verify with `npx agent-root resolve <domain>` to confirm everything works

## Full spec

See https://agentroot.io/docs/protocol for the complete protocol specification.