Claiming Your Agent Record: DNS, Well-Known File, or Repository Proof

Why Claiming Your Agent Record Matters

Claiming your agent record on Wellknown is essential for proving verified ownership of your AI agent or MCP server. Verified ownership unlocks trust and control over your record, allowing you to manage how your agent is presented and indexed. Without claiming, your record remains unverified, which may limit your ability to update or protect it.

Wellknown indexes over 85,640 records, with 27,389 currently live, making it a significant platform for AI agents and MCP servers. Claiming your record ensures your presence is authenticated and recognized in this ecosystem.

How Wellknown Sees Your Resource

Wellknown distinguishes between declared metadata—what publishers state—and observed status—what Wellknown measures by checking endpoints. Observed statuses include live, recently observed, unavailable, and unknown. Claiming your record does not change the observed status directly but establishes verified ownership, which is crucial for record management.

Targets for claim proofs are derived from the record's domain or repository, ensuring that ownership verification is tied to the actual resource location. This linkage is fundamental to the integrity of the index.

Step-by-Step How to Claim Your Agent Record

Wellknown supports three proof methods to claim your agent record:

• DNS TXT record: Add a TXT record at _wellknown.YOUR-DOMAIN containing the claim token.
• Well-known file: Host a file named wellknown-verify.txt at https://YOUR-DOMAIN/.well-known/wellknown-verify.txt with the claim token.
• Repository file: Place a .wellknown-verify file at the root of your repository containing the claim token.

To initiate a claim, you typically obtain a claim token from Wellknown and then choose one of these methods to prove control over the domain or repository.

After setting up the proof, submit your claim using the Wellknown API endpoint https://wellknown.network/api/v1/submit. This endpoint accepts your claim submission and triggers verification.

You can monitor the status of your claim and your agent record using the API paths:

• https://wellknown.network/api/v1/agents/{id} to retrieve agent details.
• https://wellknown.network/api/v1/agents/{id}/status to check the current observed status.

For programmatic interactions, Wellknown's MCP server exposes tools such as submit_agent and check_status that clients can call to manage claims and verify status.

What Changes Once Your Record Is Claimed

Once your claim is verified, your record shows verified ownership on Wellknown. This verification allows you to update your record securely and ensures that your agent or MCP server is recognized as authentic.

Verified ownership also helps prevent unauthorized changes and supports better indexing and discovery of your agent in the Wellknown network.

The claim token validity is 7 days, so timely submission and verification are important to maintain your claim.

Common Mistakes to Avoid

• Not matching the proof target: Ensure the DNS TXT record or well-known file is placed exactly at the specified location derived from your record's domain or repository.
• Expired claim tokens: Claim tokens are valid for 7 days; submitting after expiration will fail.
• Incorrect file content: The proof files must contain the exact claim token without modifications.
• Ignoring API rate limits: Anonymous submissions are limited to 5 per hour and 30 requests per minute, while keyed requests allow 120 per minute.
• Not verifying claim status: Always check your claim status using the API to confirm successful verification.

Additional Resources

For detailed documentation, visit Wellknown's official docs at https://wellknown.network/docs/claim and related pages on records, status, and MCP.

This guide is based on data current as of 2026-11-07T00:31:39.865Z.