mintlify · mintlify · Jun 5, 2026 · Jun 5, 2026
diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx
@@ -14,7 +14,7 @@
 Your search MCP server exposes tools for AI applications to search and retrieve your content. Your users must connect your search MCP server to their tools.

 <Tip>
  Looking to let agents edit your content instead of read it? Use the [admin MCP server](/ai/mintlify-mcp) for an authenticated MCP server that exposes branching, page editing, navigation, and `docs.json` tools to trusted agents.
 </Tip>

 ### How MCP servers work
@@ -26,21 +26,21 @@
 - Each tool call happens during the generation process, so the AI application uses up-to-date information from your site to generate its response.

 <Tip>
  Some AI tools like Claude support both MCP and skills. MCP gives access to your content, while skills instruct agents how to use that content effectively. They're complementary and connecting your MCP server gives agents access to both.
 </Tip>

 ### MCP tools

 Your search MCP server provides two tools that agents can use:

 - **Search**: Searches across your site to find relevant content, returning snippets with titles and links. Use this to discover information or find pages matching a query.
 - **Query docs filesystem**: Reads and navigates your site's virtual filesystem using shell-style commands. Use this to browse and retrieve content, or extract specific sections—including batch reads across multiple pages in a single call.

 Agents determine when to use each tool based on the context of the conversation. For example, an agent might first search your site to find relevant pages, then use the query docs filesystem tool to read the full content of the most relevant results.

 ### MCP resources

 Your search MCP server also exposes your [skill.md files](/ai/skillmd) as MCP resources. Agents connected to your search MCP server can discover and access your skill files without installing them separately.

 `Skill.md` resources appear in the search MCP server's resource list and contain the capability descriptions Mintlify generates or that you define in your [custom skill files](/ai/skillmd#custom-skill-files).

@@ -82,7 +82,7 @@

 ### Discovery endpoint

 Mintlify hosts a discovery document at `/.well-known/mcp` for agents and tools to locate your search MCP server without prior configuration.

 `GET /.well-known/mcp` returns a JSON document describing your search MCP server:

@@ -119,6 +119,64 @@
 
 For agent-readiness, the same discovery document is also available at `/.well-known/mcp.json`. Mintlify additionally serves an MCP server card at `/.well-known/mcp/server-card.json` and a list of server cards at `/.well-known/mcp/server-cards.json`. All discovery endpoints are served automatically and don't require configuration.
 
+#### Server card endpoints
+
+`GET /.well-known/mcp/server-card.json` returns a single server card describing your MCP server. `GET /.well-known/mcp/server-cards.json` returns a `servers` array with one card per available endpoint (always includes a public server card, and an authenticated server card when authentication is enabled).
+
+Each server card includes the standard discovery fields and a `tools` array that describes the MCP tools the server advertises. Use this to pre-populate tool metadata in MCP clients without making an `initialize` call to the server.
+
+```json
+{
+  "name": "your-docs-search",
+  "version": "1.0.0",
+  "url": "https://your-docs.com/mcp",
+  "transport": "http",
+  "description": "Search and retrieve your documentation",
+  "capabilities": {
+    "tools": true,
+    "resources": true
+  },
+  "authentication": "none",
+  "tools": [
+    {
+      "name": "search_your_docs",
+      "title": "Search documentation",
+      "description": "Search across your documentation site.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string", "description": "Search query" }
+        },
+        "required": ["query"]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    }
+  ]
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `tools[].name` | Tool name advertised over MCP. Tool names are site-specific, so use the value returned by the discovery endpoint rather than hardcoding it. |
+| `tools[].title` | Optional human-readable title for the tool. |
+| `tools[].description` | Human-readable description of what the tool does. |
+| `tools[].inputSchema` | JSON Schema for the tool's input parameters. |
+| `tools[].annotations` | Optional [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) that describe tool behavior. |
+
+The built-in search and query docs filesystem tools are advertised as read-only and non-destructive with the following annotations:
+
+- `readOnlyHint: true` — the tool does not modify any state.
+- `destructiveHint: false` — the tool has no destructive side effects.
+- `idempotentHint: true` — repeated calls with the same arguments return equivalent results.
+- `openWorldHint: false` — the tool operates against your indexed documentation rather than the open web.
+
+MCP clients can use these annotations to surface tool safety information to users or to allow read-only tools to run without explicit approval.
+
 ### Enable authenticated MCP
 
 If your site requires authentication, your search MCP server requires users to authenticate before connecting. When a user adds your MCP server URL to their AI tool, they must log in with their existing credentials. After authenticating, a redirect sends them back to their tool. The MCP server only returns content each user has permission to access based on their [user groups](/deploy/authentication-setup).

diff --git a/es/ai/model-context-protocol.mdx b/es/ai/model-context-protocol.mdx
@@ -136,6 +136,66 @@ Mintlify aloja un documento de descubrimiento en `/.well-known/mcp` para que los
 
 Para la compatibilidad con agentes, el mismo documento de descubrimiento también está disponible en `/.well-known/mcp.json`. Mintlify además expone una tarjeta de servidor MCP en `/.well-known/mcp/server-card.json` y una lista de tarjetas de servidor en `/.well-known/mcp/server-cards.json`. Todos los endpoints de descubrimiento se sirven automáticamente y no requieren configuración.
 
+<div id="server-card-endpoints">
+  #### Endpoints de la tarjeta de servidor
+</div>
+
+`GET /.well-known/mcp/server-card.json` devuelve una única tarjeta de servidor que describe tu servidor MCP. `GET /.well-known/mcp/server-cards.json` devuelve un arreglo `servers` con una tarjeta por cada endpoint disponible (siempre incluye una tarjeta de servidor pública y una tarjeta de servidor autenticada cuando la autenticación está habilitada).
+
+Cada tarjeta de servidor incluye los campos de descubrimiento estándar y un arreglo `tools` que describe las herramientas MCP que el servidor anuncia. Úsalo para precargar los metadatos de las herramientas en los clientes MCP sin tener que realizar una llamada `initialize` al servidor.
+
+```json
+{
+  "name": "your-docs-search",
+  "version": "1.0.0",
+  "url": "https://your-docs.com/mcp",
+  "transport": "http",
+  "description": "Search and retrieve your documentation",
+  "capabilities": {
+    "tools": true,
+    "resources": true
+  },
+  "authentication": "none",
+  "tools": [
+    {
+      "name": "search_your_docs",
+      "title": "Search documentation",
+      "description": "Search across your documentation site.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string", "description": "Search query" }
+        },
+        "required": ["query"]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    }
+  ]
+}
+```
+
+| Campo | Descripción |
+| --- | --- |
+| `tools[].name` | Nombre de la herramienta anunciada a través de MCP. Los nombres de las herramientas son específicos de cada sitio, así que usa el valor devuelto por el endpoint de descubrimiento en lugar de codificarlo de forma fija. |
+| `tools[].title` | Título opcional, legible por humanos, de la herramienta. |
+| `tools[].description` | Descripción legible por humanos de lo que hace la herramienta. |
+| `tools[].inputSchema` | JSON Schema de los parámetros de entrada de la herramienta. |
+| `tools[].annotations` | [Anotaciones de herramientas MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) opcionales que describen el comportamiento de la herramienta. |
+
+Las herramientas integradas de búsqueda y de consulta del sistema de archivos de la documentación se anuncian como de solo lectura y no destructivas con las siguientes anotaciones:
+
+- `readOnlyHint: true`: la herramienta no modifica ningún estado.
+- `destructiveHint: false`: la herramienta no tiene efectos secundarios destructivos.
+- `idempotentHint: true`: las llamadas repetidas con los mismos argumentos devuelven resultados equivalentes.
+- `openWorldHint: false`: la herramienta opera sobre tu documentación indexada y no sobre la web abierta.
+
+Los clientes MCP pueden usar estas anotaciones para mostrar a los usuarios información sobre la seguridad de las herramientas o para permitir que las herramientas de solo lectura se ejecuten sin aprobación explícita.
+
 <div id="enable-authenticated-mcp">
   ### Habilitar MCP autenticado
 </div>

diff --git a/fr/ai/model-context-protocol.mdx b/fr/ai/model-context-protocol.mdx
@@ -136,6 +136,66 @@ Mintlify héberge un document de découverte à l'adresse `/.well-known/mcp` pou
 
 Pour la compatibilité avec les agents, le même document de découverte est également disponible à l’adresse `/.well-known/mcp.json`. Mintlify expose en plus une carte de serveur MCP à `/.well-known/mcp/server-card.json` et une liste de cartes de serveur à `/.well-known/mcp/server-cards.json`. Tous les endpoints de découverte sont servis automatiquement et ne nécessitent aucune configuration.
 
+<div id="server-card-endpoints">
+  #### Endpoints des cartes de serveur
+</div>
+
+`GET /.well-known/mcp/server-card.json` renvoie une seule carte de serveur décrivant votre serveur MCP. `GET /.well-known/mcp/server-cards.json` renvoie un tableau `servers` contenant une carte par endpoint disponible (inclut toujours une carte de serveur publique, ainsi qu’une carte de serveur authentifiée lorsque l’authentification est activée).
+
+Chaque carte de serveur inclut les champs de découverte standards et un tableau `tools` qui décrit les outils MCP annoncés par le serveur. Utilisez-le pour pré-remplir les métadonnées des outils dans les clients MCP sans avoir à effectuer un appel `initialize` au serveur.
+
+```json
+{
+  "name": "your-docs-search",
+  "version": "1.0.0",
+  "url": "https://your-docs.com/mcp",
+  "transport": "http",
+  "description": "Search and retrieve your documentation",
+  "capabilities": {
+    "tools": true,
+    "resources": true
+  },
+  "authentication": "none",
+  "tools": [
+    {
+      "name": "search_your_docs",
+      "title": "Search documentation",
+      "description": "Search across your documentation site.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string", "description": "Search query" }
+        },
+        "required": ["query"]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    }
+  ]
+}
+```
+
+| Champ | Description |
+| --- | --- |
+| `tools[].name` | Nom de l’outil annoncé via MCP. Les noms d’outils sont spécifiques à chaque site ; utilisez donc la valeur renvoyée par l’endpoint de découverte plutôt que de la coder en dur. |
+| `tools[].title` | Titre lisible facultatif pour l’outil. |
+| `tools[].description` | Description lisible de ce que fait l’outil. |
+| `tools[].inputSchema` | JSON Schema des paramètres d’entrée de l’outil. |
+| `tools[].annotations` | [Annotations d’outils MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) facultatives qui décrivent le comportement de l’outil. |
+
+Les outils intégrés de recherche et de requête du système de fichiers de documentation sont annoncés comme étant en lecture seule et non destructifs, avec les annotations suivantes :
+
+- `readOnlyHint: true` — l’outil ne modifie aucun état.
+- `destructiveHint: false` — l’outil n’a aucun effet de bord destructeur.
+- `idempotentHint: true` — des appels répétés avec les mêmes arguments renvoient des résultats équivalents.
+- `openWorldHint: false` — l’outil opère sur votre documentation indexée plutôt que sur le web ouvert.
+
+Les clients MCP peuvent utiliser ces annotations pour présenter des informations de sécurité aux utilisateurs ou pour permettre aux outils en lecture seule de s’exécuter sans approbation explicite.
+
 <div id="enable-authenticated-mcp">
   ### Activer le MCP avec authentification
 </div>

diff --git a/zh/ai/model-context-protocol.mdx b/zh/ai/model-context-protocol.mdx
@@ -133,6 +133,68 @@ Mintlify 在 `/.well-known/mcp` 托管一个发现文档，便于智能体和工
 | `servers[].name` | 服务器条目的标识符。 |
 | `servers[].authentication` | 服务器条目的身份验证方式。 |
 
+为了便于智能体直接使用，相同的发现文档也可在 `/.well-known/mcp.json` 获取。此外，Mintlify 还会在 `/.well-known/mcp/server-card.json` 提供一个 MCP 服务器卡片，并在 `/.well-known/mcp/server-cards.json` 提供服务器卡片列表。所有发现端点均会自动提供，无需任何配置。
+
+<div id="server-card-endpoints">
+  #### 服务器卡片端点
+</div>
+
+`GET /.well-known/mcp/server-card.json` 返回一个描述你的 MCP 服务器的单个服务器卡片。`GET /.well-known/mcp/server-cards.json` 返回一个 `servers` 数组，其中每个可用端点对应一个卡片（始终包含一个公开服务器卡片；当启用身份验证时，还会包含一个已认证的服务器卡片）。
+
+每个服务器卡片都包含标准的发现字段以及一个 `tools` 数组，用于描述该服务器对外公布的 MCP 工具。你可以借助此信息在 MCP 客户端中预先填充工具元数据，而无需向服务器发起 `initialize` 调用。
+
+```json
+{
+  "name": "your-docs-search",
+  "version": "1.0.0",
+  "url": "https://your-docs.com/mcp",
+  "transport": "http",
+  "description": "Search and retrieve your documentation",
+  "capabilities": {
+    "tools": true,
+    "resources": true
+  },
+  "authentication": "none",
+  "tools": [
+    {
+      "name": "search_your_docs",
+      "title": "Search documentation",
+      "description": "Search across your documentation site.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string", "description": "Search query" }
+        },
+        "required": ["query"]
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      }
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `tools[].name` | 通过 MCP 对外公布的工具名称。工具名称因站点而异，请使用发现端点返回的值，而不要硬编码。 |
+| `tools[].title` | 工具的可选人类可读标题。 |
+| `tools[].description` | 工具功能的人类可读描述。 |
+| `tools[].inputSchema` | 工具输入参数的 JSON Schema。 |
+| `tools[].annotations` | 可选的 [MCP 工具注解](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)，用于描述工具的行为特征。 |
+
+内置的搜索和查询文档文件系统工具会以只读且非破坏性的方式对外公布，并带有以下注解：
+
+- `readOnlyHint: true` — 该工具不会修改任何状态。
+- `destructiveHint: false` — 该工具没有破坏性副作用。
+- `idempotentHint: true` — 使用相同参数重复调用会返回等价的结果。
+- `openWorldHint: false` — 该工具针对你已索引的文档进行操作，而非开放的互联网。
+
+MCP 客户端可以利用这些注解向用户呈现工具的安全性信息，或允许只读工具在无需显式批准的情况下运行。
+
 <div id="enable-authenticated-mcp">
   ### 启用 MCP 认证
 </div>