How to Publish Trusted MCP Endpoints in agent.json
An agent.json MCP endpoint entry should declare the official MCP URL, operator, auth model, scopes, docs, terms, support route, logging expectation, and proof links. The goal is simple: before an agent connects to a tool surface, it can inspect the endpoint record and verify that the endpoint belongs to the expected operator.
For HeadlessDomains.com, agent.json should be linked from a .agent identity. The .agent record anchors the manifest, while agent.json gives callers the structured details they can parse before connecting to MCP tools.
Required MCP Endpoint Fields
| Field | Purpose | Example | Review question |
|---|---|---|---|
| id | Stable endpoint label | procurement_tools | Can logs and reviews reference it? |
| url | Canonical MCP endpoint | https://tools.example.com/mcp | Is this the official URL? |
| operator | Owner or publisher | Example Enterprise | Who answers for changes? |
| auth | Authorization model | oauth_protected_resource | How are calls authorized? |
| scopes | Allowed access | quotes:read | Are scopes limited? |
| docs | Human and agent docs | docs URL | Can callers inspect use rules? |
| status | Lifecycle state | active | Is the endpoint current? |
Minimal Example
{"id":"support-tools","type":"mcp_endpoint","url":"https://tools.example.com/mcp/support","operator":"Example Support","auth":{"type":"oauth","protected_resource":"https://tools.example.com"},"scopes":["tickets:read","policies:read"],"docs":"https://tools.example.com/docs/mcp","status":"active"}Full Trusted Endpoint Example
{"agent":"support-router.agent","operator":"Example Support","mcp_endpoints":[{"id":"support_tools","url":"https://tools.example.com/mcp/support","auth":{"type":"oauth","authorization_server":"https://auth.example.com","resource":"https://tools.example.com"},"scopes":["tickets:read","refund_policy:read"],"forbidden_actions":["issue_refund","change_customer_record"],"docs":"https://tools.example.com/docs/mcp","terms":"https://tools.example.com/terms","support":"mailto:mcp-support@example.com","logging":"tool_calls_and_blocks","proof":["dns_txt","directory_profile"],"status":"active"}]}Publishing Checklist
- Choose a stable endpoint ID and canonical MCP URL.
- Name the operator and support route.
- Declare auth type, authorization server, protected resource, and token audience when applicable.
- List allowed scopes and explicitly forbidden actions.
- Link docs, terms, privacy policy, and incident contact.
- Attach proof links such as DNS TXT, public profile, source docs, or directory page.
- Set status and review cadence.
- Link agent.json from the public .agent identity record.
Where HeadlessDomains.com Fits
HeadlessDomains.com gives the manifest a public identity anchor. agent.json can describe the endpoint, but the .agent record helps callers locate the current manifest, compare proof links, inspect the profile, and verify that the endpoint belongs to the claimed operator.
Use this template with the MCP Security Checklist and the AI Agent Identity Security hub before opening tool access to production agents.
Related Reading
- What Is an MCP Gateway?
- MCP Server vs AI Agent vs Tool
- Agent Registry Checklist
- The Agent Identity Stack
Sources
- MCP authorization documentation
- Model Context Protocol specification
- Google Cloud MCP authentication
- HeadlessDomains.com
FAQ
Where should MCP endpoint metadata live?
Put endpoint metadata in agent.json or a linked manifest, then connect that file to a public .agent identity record.
What fields should be included?
Include endpoint URL, operator, auth model, scopes, docs, terms, support, proof links, logging expectation, status, and review cadence.
Should agent.json include secrets?
No. Publish only public metadata. Keep tokens, private keys, internal hostnames, and customer data out of public manifests.
How does a caller verify the endpoint?
The caller can compare the .agent record, agent.json URL, directory profile, docs, and endpoint metadata before connecting.