How to Make Your AI Agent Discoverable: A Developer's Guide

Why Agent Discovery Matters

The AI agent ecosystem is exploding. MCP servers, A2A agents, REST-based bots, and autonomous systems are being built every day — but most of them exist in isolation. A developer builds an agent that can summarize legal documents, deploys it, and... nobody finds it. Not because it isn't useful. Because there's no standard way to find it.

This is exactly the problem DNS solved for the early web. Before DNS, if you wanted to connect to a server, you needed to know its IP address. DNS created a layer of indirection — a global registry that maps human-readable names to machine-readable addresses. AgentDNS does the same thing for AI agents.

When your agent is registered on AgentDNS, any other agent can resolve it by capability in milliseconds:

curl "https://agent-dns.tech/api/v1/resolve?capability=legal-summarization&protocol=mcp"

This returns the most trusted agents matching that capability, complete with endpoints, trust scores, and communication preferences. Your agent goes from invisible to discoverable — by other agents, developers, and users searching the directory.

Step 1: Get an API Key

Registration requires a write-scoped API key. Here's how to get one:

1. Go to agent-dns.tech/register and sign in with GitHub
2. Visit your dashboard and click “Generate API Key”
3. Give it a descriptive name (e.g., “My Agent CI”)
4. Select the “Write” scope
5. Copy the key — it starts with adns_k1_

Store it as an environment variable: AGENTDNS_API_KEY=adns_k1_...

Step 2: Register Your Agent

Send a POST to /api/v1/agents with your agent's details. Here's a minimal registration:

curl -X POST "https://agent-dns.tech/api/v1/agents" \
  -H "Authorization: Bearer $AGENTDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-doc-analyzer",
    "name": "My Document Analyzer",
    "tagline": "Analyzes legal and financial documents via MCP",
    "capabilities": ["document-analysis", "summarization", "legal"],
    "protocols": ["mcp"],
    "mcp_server_url": "https://my-agent.example.com/mcp",
    "docs_url": "https://docs.my-agent.example.com",
    "pricing_model": "free"
  }'

The response includes your agent's id, slug, and a link to its profile page at /agent/my-doc-analyzer.

Step 3: Understand the Schema

A complete agent registration can include:

• slug (required): Your agent's unique identifier. URL-safe, lowercase, hyphens. This becomes agent-dns.tech/agent/your-slug.
• name (required): Human-readable name.
• tagline: One-line description. This is what shows in search results.
• description: Full markdown description. Explain what your agent does, use cases, limitations.
• capabilities: Array of capability tags. This is the most important field for discovery.
• protocols: mcp, a2a, rest, graphql, websocket
• mcp_server_url: Where to connect via MCP
• a2a_endpoint: Your A2A agent card URL (usually /.well-known/agent.json)
• api_endpoint: REST API base URL
• docs_url: Your documentation
• pricing_model: free, per-task, subscription, usage-based, custom

Step 4: Choose Capability Tags Wisely

Capabilities are the core of how agents find each other. When another agent calls /resolve?capability=legal-summarization, it gets back every agent tagged with that capability, ranked by trust score.

Best practices for capability tagging:

• Be specific: contract-review is better than legal. Specific tags reduce false positives.
• Layer from general to specific: Use both summarization AND legal-document-summarization. This catches both broad and precise searches.
• Use hyphens, lowercase only: code-generation not Code Generation
• Look at existing agents: Browse the directory to see which capability tags similar agents use. Consistency helps discovery.
• Include the action verb: pdf-extraction is clearer than just pdf
• Don't keyword-stuff: Agents with 50 generic capabilities score lower on relevance than those with 5 precise ones

Common capability patterns to follow:

# Domain: what domain does your agent operate in?
"legal", "finance", "engineering", "healthcare", "content"

# Action: what does it do?
"summarization", "analysis", "generation", "translation", "extraction"

# Interface: how does it connect?
"browser-automation", "database", "api-integration"

# Output format: what does it produce?
"json-output", "markdown-generation", "pdf-export"

Step 5: Keep Your Registration Current

Agent discovery only works if the registry is accurate. Update your registration whenever your agent's capabilities or endpoints change:

curl -X PATCH "https://agent-dns.tech/api/v1/agents/my-doc-analyzer" \
  -H "Authorization: Bearer $AGENTDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tagline": "Now supports 40+ document formats",
    "capabilities": ["document-analysis", "summarization", "legal", "pdf-extraction", "ocr"]
  }'

Consider adding AgentDNS registration to your CI/CD pipeline. When you deploy a new version, automatically update your registration. See our GitHub Action integration guide for a ready-to-use workflow.

Step 6: Add A2A Discovery

For full agent-to-agent interoperability, publish a /.well-known/agent.json file on your domain. This is the A2A Agent Card — a structured description of your agent that any A2A-compatible system can discover automatically.

{
  "name": "My Document Analyzer",
  "description": "Analyzes legal and financial documents",
  "url": "https://my-agent.example.com",
  "version": "1.2.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["bearer"],
    "credentials": "API key from https://my-agent.example.com/keys"
  },
  "skills": [
    {
      "id": "analyze_document",
      "name": "Analyze Document",
      "description": "Analyzes a document and returns structured findings",
      "tags": ["legal", "document-analysis", "summarization"]
    }
  ]
}

Then register your A2A endpoint with AgentDNS:

curl -X PATCH "https://agent-dns.tech/api/v1/agents/my-doc-analyzer" \
  -H "Authorization: Bearer $AGENTDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "a2a_endpoint": "https://my-agent.example.com/.well-known/agent.json",
    "protocols": ["mcp", "a2a"]
  }'

Step 7: Use the MCP Server

Want to let agents discover AgentDNS itself? Use the official MCP server:

npx @agentdns/mcp-server

Add this to your Claude Desktop config or any MCP client:

{
  "mcpServers": {
    "agentdns": {
      "command": "npx",
      "args": ["@agentdns/mcp-server"],
      "env": {
        "AGENTDNS_API_KEY": "adns_k1_YOUR_KEY"
      }
    }
  }
}

Now any agent running in that context can call search_agents, resolve_by_capability, register_agent, and more — all via natural language tool calls.

Checklist: Making Your Agent Discoverable

• ✅ Registered on AgentDNS with accurate capabilities
• ✅ Capability tags are specific and consistent with the ecosystem
• ✅ Tagline is clear and action-oriented
• ✅ At least one endpoint URL (MCP, A2A, or REST)
• ✅ Pricing model set correctly
• ✅ /.well-known/agent.json published on your domain
• ✅ Registration updates automated via CI/CD or GitHub Action
• ✅ /.well-known/agents.json on your domain (emerging standard)

What Happens Next

Once registered, your agent appears in:

• The public directory at agent-dns.tech/explore
• API search results for matching capability queries
• The MCP server when other Claude instances search for agents
• The OpenAPI spec at /api/v1/openapi.json for automated tooling
• The A2A agent card at /.well-known/agent.json

Every time your agent is queried via AgentDNS, its lookup count increases — building the trust score that helps it rank higher in results over time.

Start now: register your agent in under 5 minutes.