--- title: "Well-Known Discovery Endpoints" description: "Standardized /.well-known/ paths that let agents and protocols discover your capabilities programmatically" url: "https://agentsurface.dev/docs/discovery/well-known-endpoints" lastVerified: 2026-09-25 lastModified: 2026-09-25T08:44:29.000Z --- ## Summary [#summary] /.well-known/ is an IETF standard (RFC 5785) for site-wide metadata. Agents use it for capability discovery without prior knowledge. Key files include API Catalog, MCP Server Cards, Agent Skills indexes, OAuth protected-resource metadata, Web Bot Auth key directories, and agent cards. Publishing these enables agents to discover and use your system programmatically. * /.well-known/api-catalog: RFC 9727 API catalog for API specs, docs, and status * /.well-known/mcp/server-card.json: MCP server metadata before connection * /.well-known/agent-skills/index.json: domain skills agents can load * /.well-known/oauth-protected-resource: OAuth resource metadata * /.well-known/security.txt: RFC 9116 vulnerability disclosure contact * /.well-known/http-message-signatures-directory: Web Bot Auth public keys * Serve JSON files as `application/json`, the API catalog as `application/linkset+json` and `security.txt` as `text/plain` * Send Access-Control-Allow-Origin on these files so browser-based agents can fetch them cross-origin The `/.well-known/` directory is an IETF-standardized location (RFC 5785) for site-wide metadata that any client can find without prior knowledge. Browsers use it for security policies and certificate verification. Agents use it for capability discovery. Publishing the right files here lets compatible agents and protocols find your capabilities without out-of-band configuration. ## /.well-known/api-catalog [#well-knownapi-catalog] API Catalog (RFC 9727) gives agents one place to discover public APIs, their specs, docs, status pages, and related metadata. Use it when a product exposes APIs that should be callable or wrapped as tools. The catalog is a linkset ([RFC 9264](https://www.rfc-editor.org/rfc/rfc9264.html)). The first entry is anchored at the catalog itself and lists each API with an `item` link. Each API can then have its own entry with typed links: `service-desc` for the machine-readable spec, `service-doc` for human docs, `service-meta` for other metadata and `status` for a status page. Serve it as `application/linkset+json;profile="https://www.rfc-editor.org/info/rfc9727"`. ```json { "linkset": [ { "anchor": "https://example.com/.well-known/api-catalog", "item": [{ "href": "https://api.example.com/v1", "title": "Public REST API" }] }, { "anchor": "https://api.example.com/v1", "service-desc": [ { "href": "https://api.example.com/openapi.json", "type": "application/vnd.oai.openapi+json" } ], "service-doc": [{ "href": "https://example.com/docs/api", "type": "text/html" }], "status": [{ "href": "https://status.example.com", "type": "text/html" }] } ] } ``` Reference the catalog with an HTTP `Link` header where practical, using the header mechanism [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html) (Web Linking) defines. The highest-value placement is your homepage response, since that's the page most crawlers and agents fetch first: ```http Link: ; rel="api-catalog" ``` ## /.well-known/ai [#well-knownai] The IETF draft "AI Discovery Endpoint" defines `/.well-known/ai` as a JSON file describing a site's AI-facing capabilities. This is the broadest of the well-known files - it covers what AI systems can do with your site, what formats you support, and where to find more specific declarations. Maximum file size: 64 KB. ```json { "version": "1.0", "name": "Acme Platform", "description": "Developer platform for building and deploying applications", "url": "https://example.com", "capabilities": ["api", "mcp", "llms-txt", "openapi", "webhooks"], "api": { "base_url": "https://api.example.com/v2", "spec": "https://api.example.com/openapi.json", "authentication": { "type": "oauth2", "token_url": "https://auth.example.com/oauth/token", "scopes_url": "https://docs.example.com/api/scopes" } }, "mcp": { "endpoint": "https://mcp.example.com", "transports": ["streamable-http"], "documentation": "https://docs.example.com/mcp" }, "llms": { "index": "https://docs.example.com/llms.txt", "full": "https://docs.example.com/llms-full.txt" }, "content": { "markdown": true, "vary_accept": true, "formats": ["text/html", "text/markdown", "application/json"] }, "contact": { "developer_support": "https://example.com/support", "status": "https://status.example.com" } } ``` Serve with `Content-Type: application/json`. This file is still a draft standard - field names may change before finalization. ## /.well-known/agent-card.json [#well-knownagent-cardjson] The Agent-to-Agent (A2A) protocol, originated by Google, uses `agent-card.json` for agent-to-agent discovery. Google transferred the protocol to the Linux Foundation in June 2025, and in August 2026 it became a hosted project of the Agentic AI Foundation (AAIF), which now governs it alongside sibling projects rather than any single vendor. When one agent wants to delegate a task to another agent, it fetches the target's agent card to understand capabilities, authentication requirements, and endpoint locations. ```json { "name": "Acme Deployment Agent", "description": "Deploys and manages applications on the Acme platform. Can create deployments, roll back, scale, and inspect logs.", "version": "1.2.0", "url": "https://agent.example.com", "documentationUrl": "https://docs.example.com/agents/deployment", "iconUrl": "https://example.com/agent-icon.png", "provider": { "organization": "Acme Inc", "url": "https://example.com" }, "capabilities": { "streaming": true, "pushNotifications": true, "stateTransitionHistory": true, "multiTurn": true }, "authentication": { "schemes": ["Bearer"], "credentials": "https://auth.example.com/agent/token" }, "defaultInputModes": ["text/plain", "application/json"], "defaultOutputModes": ["text/plain", "application/json"], "skills": [ { "id": "deploy", "name": "Deploy Application", "description": "Creates a new deployment from a git ref or artifact URL. Returns a deployment ID for status tracking.", "tags": ["deploy", "ci", "release"], "examples": [ "Deploy the main branch to production", "Roll back to the previous deployment", "Deploy version 2.4.1 to staging" ], "inputModes": ["text/plain", "application/json"], "outputModes": ["application/json"] }, { "id": "logs", "name": "Fetch Logs", "description": "Retrieves logs for a deployment. Supports filtering by time range, severity, and service.", "tags": ["logs", "observability", "debug"], "examples": [ "Show me the last 100 error logs", "Get logs from the auth service in the last hour" ], "inputModes": ["text/plain", "application/json"], "outputModes": ["text/plain", "application/json"] } ] } ``` The A2A protocol uses this card for routing - an orchestrating agent looks up the skills array to decide whether to delegate a task here. The `examples` field in each skill is particularly important: these are used for semantic matching when an agent does not know your agent's ID but is searching for a capable agent by task description. ## /.well-known/mcp/server-card.json [#well-knownmcpserver-cardjson] An MCP Server Card describes a remote MCP server before an agent connects: what it does, which transport it uses, how to authenticate, and which tools are available. Prefer this over hiding the endpoint in prose. ```json { "version": "1.0", "serverInfo": { "name": "docs-search", "title": "Documentation Search", "version": "1.0.0" }, "description": "Search public documentation and retrieve canonical pages.", "transport": { "type": "streamable-http", "endpoint": "https://example.com/mcp" }, "tools": [ { "name": "search_docs", "description": "Full-text search across published documentation." }, { "name": "get_page", "description": "Fetch one page by canonical URL." } ], "authentication": { "required": false } } ``` ## /.well-known/mcp.json [#well-knownmcpjson] Some clients and proposals use `/.well-known/mcp.json` as a compatibility pointer. Prefer `/.well-known/mcp/server-card.json` for rich server metadata, and keep `mcp.json` only as a redirect or pointer when needed: ```json { "version": "1.0", "servers": [ { "name": "Acme MCP Server", "description": "Full API access via MCP. Tools for deployments, projects, and team management.", "url": "https://mcp.example.com", "transport": "streamable-http", "authentication": { "type": "oauth2", "authorization_url": "https://auth.example.com/oauth/authorize", "token_url": "https://auth.example.com/oauth/token", "scopes": { "deployments:read": "Read deployment status and logs", "deployments:write": "Create and modify deployments", "projects:read": "List and inspect projects", "projects:write": "Create and modify projects" } }, "capabilities": { "tools": true, "resources": true, "prompts": true, "sampling": false } } ] } ``` This format is still evolving. If you publish it, use it as a compatibility pointer or redirect to the MCP Server Card rather than the only advertised metadata. ### WebMCP - Tools Exposed In-Browser [#webmcp---tools-exposed-in-browser] The well-known MCP files above advertise a *remote* MCP server. [WebMCP](/docs/protocols/webmcp) is the browser-side counterpart: a W3C Community Group draft that lets a site expose page-scoped tools through `document.modelContext`. It does not prescribe the remote MCP wire protocol, and a client must visit the page to discover its tools. Chrome's origin trial begins in Chrome 149, but the API remains a draft without a cross-browser commitment. Publish remote MCP metadata for capabilities that must work without loading the UI. ## /.well-known/agent-skills/index.json [#well-knownagent-skillsindexjson] Publish an Agent Skills index when your site can teach agents how to complete domain-specific tasks. The index should point to separate skill documents rather than inline long procedures. Each linked skill should follow the public Agent Skills format: a folder with a `SKILL.md` file, required `name` and `description` frontmatter, and optional `scripts/`, `references/`, and `assets/` directories. Keep skill descriptions specific because compatible agents load only the catalog first, then activate the full skill through progressive disclosure. ```json { "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", "skills": [ { "name": "create-api-token", "type": "skill-md", "description": "Use when an agent needs to create a scoped API token for automation.", "url": "https://example.com/.well-known/agent-skills/create-api-token/SKILL.md", "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" } ] } ``` Use the discovery v0.2 schema and hash the exact served `SKILL.md` bytes. Validation must fetch the linked artifact, compare its SHA-256 with `digest`, parse its frontmatter, and confirm the description says when to use it. A valid index pointing to an HTML shell, login page, empty document, malformed skill, or mismatched digest is not a working discovery surface. ## /.well-known/oauth-protected-resource [#well-knownoauth-protected-resource] Protected Resource Metadata (RFC 9728) lets agents discover which authorization server, scopes, and token validation rules apply before calling a protected API. Use the full guide in [Protected Resource Metadata](/docs/authentication/protected-resource-metadata) for schema details. ## /.well-known/security.txt [#well-knownsecuritytxt] [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116.html) defines `security.txt` as a machine-parsable file describing an organization's vulnerability disclosure process. It predates the agent ecosystem and isn't agent-specific, but it's a low-cost trust signal: an agent assessing whether a site is operationally credible can find a verified security contact without guessing at `security@` or hunting for a contact form. Two fields are mandatory - `Contact` and `Expires` - the rest are optional: ``` Contact: mailto:security@example.com Expires: 2027-01-01T00:00:00.000Z Policy: https://example.com/security-policy ``` Serve it at `/.well-known/security.txt` with `Content-Type: text/plain; charset=utf-8`. ## CORS on Public Discovery Files [#cors-on-public-discovery-files] Browser-hosted agents and tools can only fetch a file cross-origin if the response sends `Access-Control-Allow-Origin`. This applies to every file on this page - `/.well-known/*`, `llms.txt`, `openapi.json`, MCP server cards - since none of them carry credentials that CORS would need to protect. No spec in this list mandates it. [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html) (OAuth Authorization Server Metadata) and [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html) (OAuth Protected Resource Metadata) say nothing about CORS, and the ratified [MCP specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http) doesn't address it either - its only CORS-adjacent text is an `Origin` header check required to prevent DNS rebinding attacks on local servers, which is unrelated to allowing cross-origin reads. An open MCP server-card discovery proposal recommends `Access-Control-Allow-Origin: *`, but it isn't part of the ratified spec. Treat CORS on these files as operational hygiene rather than compliance: public, non-sensitive metadata costs nothing to open up, and doing so unblocks any browser-based agent that would otherwise be silently blocked by the same-origin policy. ``` Access-Control-Allow-Origin: * ``` ## /.well-known/http-message-signatures-directory [#well-knownhttp-message-signatures-directory] Web Bot Auth uses signed HTTP requests so a site can identify friendly bots and agents. The signatures directory publishes public keys that receiving sites use to verify requests. Implement this when your service sends outbound bot or agent requests and wants other sites to distinguish it from anonymous automation. ## /.well-known/acp.json [#well-knownacpjson] The Agentic Commerce Protocol (ACP) uses `acp.json` for capability advertisement. ACP focuses on commercial agent interactions - agents that can transact, book, purchase, or negotiate on behalf of users. ```json { "version": "1.0", "provider": { "name": "Acme Inc", "url": "https://example.com", "description": "Developer platform and marketplace" }, "capabilities": [ { "type": "api_access", "description": "Programmatic access to all platform features", "endpoint": "https://api.example.com/v2", "pricing": "per_request", "documentation": "https://docs.example.com/api" }, { "type": "subscription_management", "description": "Purchase and manage platform subscriptions", "endpoint": "https://api.example.com/v2/billing", "documentation": "https://docs.example.com/billing" } ], "contact": { "technical": "api@example.com", "commercial": "partnerships@example.com" } } ``` ## /openapi.json [#openapijson] While not technically a `/.well-known/` path, `/openapi.json` and `/openapi.yaml` are the de facto standard locations for OpenAPI specifications. Many API clients, agent frameworks, and developer tools check these paths automatically. Serve your primary OpenAPI spec at one of these conventional paths: ``` /openapi.json ← most commonly checked /openapi.yaml ← for teams that prefer YAML /api/openapi.json ← if your API lives under /api /api-docs ← Swagger UI convention ``` Redirect from all conventional paths to your canonical spec location rather than serving different files at each path. Agents that hit a redirect follow it; the canonical URL stays stable. ## agents.txt [#agentstxt] The IETF draft "Agent Capability Declaration" proposes `agents.txt` as a text file (at `/agents.txt`) that declares agent-accessible capabilities in a human- and machine-readable format: ``` # agents.txt # Agent capability declaration for example.com Name: Acme Platform Version: 2.4 Contact: api@example.com # API Capabilities API: https://api.example.com/v2 API-Spec: https://api.example.com/openapi.json API-Auth: oauth2-client-credentials API-Docs: https://docs.example.com/api # MCP MCP: https://mcp.example.com MCP-Transport: streamable-http # LLM Index LLM-Index: https://docs.example.com/llms.txt LLM-Full: https://docs.example.com/llms-full.txt # Content Markdown: yes Vary-Accept: yes ``` The format is `Key: Value`, one declaration per line. Comments begin with `#`. This draft is early-stage and field names are not finalized. ## agents.json [#agentsjson] The Wildcard AI standard uses `agents.json` to describe structured workflows - sequences of actions that agents can perform using your API: ```json { "version": "1.0", "name": "Acme Platform", "description": "Developer platform for building and deploying applications", "api": { "base_url": "https://api.example.com/v2", "spec": "https://api.example.com/openapi.json", "auth": { "type": "bearer", "token_url": "https://auth.example.com/oauth/token" } }, "flows": [ { "id": "deploy_application", "name": "Deploy an Application", "description": "Create a new deployment from a git ref and wait for it to complete", "steps": [ { "id": "create_deployment", "action": "POST /deployments", "description": "Create the deployment", "required_params": ["project_id", "ref"], "optional_params": ["environment", "strategy"] }, { "id": "poll_status", "action": "GET /deployments/{deployment_id}", "description": "Poll until status is 'complete' or 'failed'", "depends_on": "create_deployment", "poll": { "field": "status", "terminal_values": ["complete", "failed"], "interval_seconds": 5, "timeout_seconds": 300 } } ], "success_output": "deployment_id, deployment_url, duration_seconds", "failure_output": "deployment_id, error_message, failed_step" } ] } ``` The `flows` array is the distinguishing feature of `agents.json`. Rather than just listing endpoints, it describes complete workflows - what to call, in what order, with what dependencies. Agents can execute a named flow without needing to reason about sequencing themselves. ## NLWeb /ask [#nlweb-ask] NLWeb, published by Microsoft, adds a `/ask` endpoint that provides a conversational interface to any site's content. An agent sends a natural-language question; the site answers it directly rather than returning a list of links. NLWeb implementations also expose an MCP server interface, making the endpoint usable both for direct HTTP calls and through MCP-compatible agent frameworks. ``` GET /ask?q=How+do+I+authenticate+with+the+API Accept: application/json ``` ```json { "question": "How do I authenticate with the API?", "answer": "Authentication uses OAuth 2.0 Client Credentials. POST to https://auth.example.com/oauth/token with grant_type=client_credentials, client_id, and client_secret. The response contains an access_token valid for 3600 seconds. Include it in all API requests as Authorization: Bearer {token}.", "sources": [ { "title": "Authentication Guide", "url": "https://docs.example.com/authentication", "excerpt": "..." } ], "confidence": 0.94 } ``` The NLWeb reference implementation is available at `github.com/nlweb-ai/NLWeb`. It connects to your existing content (via `llms.txt` or a vector database) and generates answers using a configured LLM backend. ## Advertising Well-Known Files [#advertising-well-known-files] Once you have published well-known files, reference them from: **Your `llms.txt`:** ```markdown ## API & Integration - [OpenAPI Specification](https://api.example.com/openapi.json): Full REST API specification - [MCP Server](https://docs.example.com/mcp): Connect via Model Context Protocol - [API Catalog](https://example.com/.well-known/api-catalog): Machine-readable API discovery ## Discovery - [AI Capabilities](https://example.com/.well-known/ai): Machine-readable capability declaration - [Agent Card](https://example.com/.well-known/agent-card.json): A2A protocol discovery - [Agent Skills](https://example.com/.well-known/agent-skills/index.json): Reusable task guides for agents ``` **Your `robots.txt`:** ``` # AI discovery files # ai-discovery: https://example.com/.well-known/ai # agent-card: https://example.com/.well-known/agent-card.json # mcp: https://example.com/.well-known/mcp/server-card.json ``` **Your OpenAPI spec:** ```yaml info: x-mcp-server: https://mcp.example.com x-agent-card: https://example.com/.well-known/agent-card.json x-llms-txt: https://docs.example.com/llms.txt ``` Cross-referencing your discovery files helps agents that start discovery from any entry point find the full picture. ## ARD and AI Catalog [#ard-and-ai-catalog] `/.well-known/ard.json` and `/.well-known/ai-catalog.json` belong to distinct evolving discovery specifications. See [Agent Catalogs and Structured Feeds](/docs/discovery/catalogs-and-feeds) for their schema boundaries, trust claims, consumer compatibility, and verification. Neither replaces the RFC 9727 API Catalog above.