Watch

adam jones d43d0bfeef

docs: fix DNS authentication to use root domain instead of _mcp-registry subdomain (#388 )

Fixes #385

Updates DNS authentication documentation to correctly specify that TXT
records should be placed at the root domain (e.g., `example.com`) rather
than the `_mcp-registry` subdomain.

The implementation correctly looks up TXT records at the root domain,
but the documentation incorrectly instructed users to create records at
`_mcp-registry.<domain>`. This mismatch was causing authentication
failures.

## Why use root domain instead of subdomain?

The root domain approach is clearer: if you want to publish to
`com.example/my-server`, you authenticate with `example.com`, not
`_mcp-registry.example.com`.

It also aligns with other TXT DNS standards, e.g. SPF. (That said, there
are other DNS standards that use subdomains e.g. DKIM 🤷)

## Changes
- Updated publish-server.md to remove `_mcp-registry.` prefix from DNS
examples
- Updated CLI commands reference documentation  
- Updated namespacing explanation documentation

2025-09-09 14:42:37 +03:00

1.6 KiB

Raw Permalink Blame History

Namespacing and Security

Namespacing prevents name squatting, makes impersonation and typo squatting much harder, and provides attribution through domain-based identity.

For practical steps on how to authenticate for different namespaces, see the publishing guide.

Namespace Format

All server names follow reverse-DNS format. Examples:

io.github.alice/weather-server - GitHub user alice
com.acme/internal-tool - Company domain acme.com
org.nonprofit.research/data-analyzer - Subdomain research.nonprofit.org

Security Model

Ownership Verification

Publishing to a namespace requires proving you control the corresponding identity:

GitHub namespaces (io.github.*):

OAuth login to GitHub account/organization
OIDC tokens in GitHub Actions workflows

Domain namespaces (com.company.*):

DNS verification: TXT record at company.com
HTTP verification: File at https://company.com/.well-known/mcp-registry-auth

Namespace Scoping

Different authentication methods grant different namespace access:

GitHub OAuth/OIDC:

io.github.username/* (for personal accounts)
io.github.orgname/* (for organizations)

DNS verification:

com.domain/* and com.domain.*/* (domain + all subdomains)

HTTP verification:

com.domain/* only (exact domain, no subdomains)

Limitations

Domain ownership changes: If someone loses/sells a domain, they lose publishing rights. Similarly if someone gains a domain, they gain publishing rights. Package validation: Registry validates namespace ownership, but actual packages may still be malicious etc.

1.6 KiB Raw Permalink Blame History