agent-discoverability

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agent Discoverability, Agent Skill

Make a product you operate, and specifically **the MCP server it exposes**, discoverable and connectable **by other AI agents**. This is the **publish / register** side of agent discovery: you own an endpoint and you want third-party agents (and the humans directing them) to find it, trust it, and complete an auth handshake against it. It is product-agnostic; `customdomain.ai` is used only as a worked example (its MCP at `https://app.customdomain.ai/mcp`, its docs at `app.customdomain.ai`).

The boundary matters. Connecting to and driving an existing MCP as a **client** is [[everjust-agent-mcp]], not this. Getting a marketing site cited by **search / answer engines** (SEO, JSON-LD, sitemap, IndexNow) is [[everjust-website-seo]], not this. This skill covers only the four surfaces an agent walks to go from "a domain" to "a working MCP session": the **registry listing**, the **OAuth discovery chain**, the **capability manifest**, and **DNS-AID** records.

## When to use this skill

- **List an MCP server in the official registry**, claim a reverse-DNS namespace (e.g. `com.customdomain/*`), prove domain ownership via a DNS TXT record, publish a `server.json`, then mirror the listing to the community directories agents browse (mcp.so, Smithery, Glama, PulseMCP). This is the single highest-leverage lever for "agents find us" in a category nobody owns.
- **Fix a remote MCP that clients "cannot connect to" even though it is up**, almost always a broken OAuth discovery chain: a protected endpoint that does not answer an unauthenticated request with `401` + a `WWW-Authenticate: Bearer` header carrying `resource_metadata`, or a missing `/.well-known/oauth-protected-resource` / `/.well-known/oauth-authorization-server`. Clients cannot start auth, so the connection silently fails.
- **Serve an agent capability manifest**, a `/.well-known/agent/mcp.json` (or equivalent) describing `protocol=mcp`, transport, the tool list, and auth. This is the doc DNS-AID's SVCB `cap=` parameter and directory listings point at.
- **Publish DNS-AID records**, SVCB + TXT + an `_index._agents` TXT + a TLSA/DANE record under a DNSSEC-signed zone, so an agent can resolve `mcp.<domain>` to your endpoint with DNS-native trust, then `dns-aid verify` it.
- **Wire cert rotation to the TLSA record**, if the same system issues and renews the TLS cert AND writes DNS (a custom-domain product does), keep the DANE `TLSA` record in lockstep on every cert rotation. Most operators cannot do this cleanly, so it is a real differentiator, not a checkbox.

**Do NOT use this skill for**, and stop if the task is really:
- **Operating a tenant's MCP as a client**, reading/writing records over someone's existing MCP, minting the Bearer key, driving the tools. That is [[everjust-agent-mcp]] (the connect/consume side). This skill is the opposite direction: making an endpoint YOU own connectable.
- **Search / answer-engine discoverability**, per-page SEO metadata, sitemap/robots, schema.org JSON-LD `sameAs`, IndexNow, getting cited by ChatGPT Search / Perplexity / Google AI Overviews. That is [[everjust-website-seo]]. `llms.txt` also lives there; here it is only a minor complement (see Pitfall 7).
- **Registrar DNS mechanics**, creating the raw TXT/SVCB/TLSA records at the registrar or DNS provider is a means, not the goal; for GoDaddy/Route 53 record CRUD see [[godaddy-api]]. This skill tells you WHICH records to publish and how to verify the chain; it does not re-teach a registrar API.
- **Standing up the MCP server itself**, building the addon/endpoint that answers MCP is platform work ([[everjust-platform]] for the EverJust case). This skill assumes the endpoint exists and makes it *discoverable*.

---

## The four surfaces (what an agent actually walks)

An agent goes from a bare domain to a live MCP session by walking these, roughly in this order. Each is independent: you can ship the registry listing without DNS-AID, or the OAuth chain without a manifest, but a connection only *completes* when the OAuth chain is intact. Publish all four for full coverage.

| Surface | Where it lives | What it answers for the agent | Failure mode if absent |
|---|---|---|---|
| **Official registry listing** | `registry.modelcontextprotocol.io` + mirrors (mcp.so, Smithery, Glama, PulseMCP) | "Does an MCP for this product/category exist, and what is its URL + transport + auth?" | Agents/users never learn the server exists; you are invisible in the directories they browse. |
| **OAuth discovery chain** | the MCP endpoint's `401` + `WWW-Authenticate`, then `/.well-known/oauth-protected-resource` (RFC 9728), then `/.well-known/oauth-authorization-server` (RFC 8414) | "This endpoint needs auth, where do I authenticate, and how?" | Client sees a `401`/`403` with no pointer and gives up. The #1 reason a remote MCP "won't connect" despite being up. |
| **Capability manifest** | `/.well-known/agent/mcp.json` (served over HTTPS) | "What protocol/transport does it speak, what tools does it expose, what auth does it want, before I even connect?" | No pre-connect introspection; DNS-AID `cap=` and directory cards have nothing to point at. |
| **DNS-AID records** | the DNS zone: `SVCB`, `TXT`, `_index._agents.<domain> TXT`, `TLSA`, under DNSSEC | "Resolve this domain to its agent endpoint(s), with DNS-native (DNSSEC + DANE) trust, without trusting a directory." | No DNS-layer discovery; agents that resolve by domain (not by directory) can't find or trust the endpoint. |

`customdomain.ai` worked example used throughout: MCP endpoint `https://app.customdomain.ai/mcp`, base domain `customdomain.ai`, agent host `mcp.customdomain.ai`, reverse-DNS namespace `com.customdomain`.

---

## Recipes

Every command below is copy-pasteable; replace the angle-bracket placeholders. Never commit a real token: use `<CF_API_TOKEN>` / `$CF_API_TOKEN`, `~/.ssh/<deploy-key>.pem`, etc.

### 1. List the MCP server in the official registry (highest leverage)

`registry.modelcontextprotocol.io` is the canonical upstream; the community directories (mcp.so, Smithery, Glama, PulseMCP) mirror or ingest from it and are what agents and users actually browse. You (a) claim a reverse-DNS namespace, (b) prove you own the matching domain via a DNS TXT record, (c) publish a `server.json`.

Author the `server.json` (this is the record other tools render):

```jsonc
{
  "name": "com.customdomain/mcp",
  "description": "Buy, connect, and manage custom domains (DNS + SSL + edge) over MCP.",
  "repository": { "url": "https://github.com/ever-just/customdomain", "source": "github" },
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://app.customdomain.ai/mcp"
    }
  ]
}
```

Namespace = reverse DNS of the domain you control: own `customdomain.ai`, so claim `com.customdomain/*`. Prove ownership by publishing the TXT record the registry's publisher CLI tells you to (a per-account verification value), e.g.:

```bash
# The publisher flow prints the exact host + value; publish it at your DNS provider.
# Example shape (value comes FROM the CLI, do not invent it):
#   _mcp-registry.customdomain.ai.  TXT  "mcp-verify=<VALUE-FROM-CLI>"

# Then publish (the official CLI is 'mcp-publisher'; auth is DNS-based for the namespace):
mcp-publisher login dns --domain customdomain.ai
mcp-publisher publish            # reads ./server.json in the working dir
```

Then submit / claim the same server on the directories agents browse (each has its own "add server" or GitHub-based submission flow): **mcp.so**, **Smithery** (`smithery.ai`), **Glama** (`glama.ai`), **PulseMCP** (`pulsemcp.com`). Point every listing at the same `https://app.customdomain.ai/mcp` and the same capability manifest URL so they stay consistent. Verify the upstream took by fetching it back (recipe 5).

### 2. Fix / verify the OAuth discovery chain (the #1 silent-failure)

A protected MCP endpoint MUST make an **unauthenticated** request fail in a way the client can follow. The chain is three hops:

1. Endpoint returns **`401 Unauthorized`** with a `WWW-Authenticate: Bearer` header whose `resource_metadata` points at the protected-resource doc:

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.customdomain.ai/.well-known/oauth-protected-resource"
```

2. `/.well-known/oauth-protected-resource` (RFC 9728, Protected Resource Metadata) names the resource and points at its authorization server(s):

```jsonc
// GET https://app.customdomain.ai/.well-known/oauth-protected-resource
{
  "resource": "https://app.customdomain.ai/mcp",
  "authorization_servers": ["https://auth.customdomain.ai"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp:read", "mcp:write"]
}
```

3. `/.well-known/oauth-authorization-server` on that auth server (RFC 8414) exposes the OAuth endpoints the client drives (authorize, token, registration):

```jsonc
// GET https://auth.customdomain.ai/.well-known/oauth-authorization-server
{
  "issuer": "https://auth.customdomain.ai",
  "authorization_endpoint": "https://auth.customdomain.ai/authorize",
  "token_endpoint": "https://auth.customdomain.ai/token",
  "registration_endpoint": "https://auth.customdomain.ai/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}
```

Test all three hops from the shell before blaming the client:

```bash
# Hop 1: unauthenticated hit MUST be 401 and carry a resource_metadata pointer.
curl -si https://app.customdomain.ai/mcp | grep -i -E 'HTTP/|www-authenticate'

From ever-just/agentskills, MIT.

More from ever-just/agentskills