Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions ai/model-context-protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Check warning on line 17 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L17

Use 'AGENTS' instead of 'agents'.

Check warning on line 17 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L17

Use 'AGENTS' instead of 'agents'.
</Tip>

### How MCP servers work
Expand All @@ -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.

Check warning on line 29 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L29

Use 'AGENTS' instead of 'agents'.

Check warning on line 29 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L29

Use 'AGENTS' instead of 'agents'.
</Tip>

### MCP tools

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

Check warning on line 34 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L34

Use 'AGENTS' instead of 'agents'.

- **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.

Check warning on line 39 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L39

Use 'AGENTS' instead of 'Agents'.

### 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.

Check warning on line 43 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L43

Use 'AGENTS' instead of 'Agents'.

`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).

Expand Down Expand Up @@ -69,20 +69,22 @@
* For content with partial authentication, where some pages are public and others require login, you must enable your search MCP server before users can access it. Unauthenticated users can search public content. Users who authenticate can search all content they have permission to access based on their [user groups](/deploy/authentication-setup).
* For content where all pages require authentication, you must enable your search MCP server before it is available to users. Users must authenticate before connecting to your search MCP server. Your search MCP server searches only the content each user has access to based on their [user groups](/deploy/authentication-setup).

View and copy your search MCP server URL on the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard.
If authentication is enabled, view and copy your search MCP server URL on the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard, under the **Hosted MCP** tab.

Check warning on line 72 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L72

Use the Oxford comma in 'If authentication is enabled, view and'.

Check warning on line 72 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L72

In general, use active voice instead of passive voice ('is enabled').

<Note>
The **Hosted MCP** tab only appears when [authentication](/deploy/authentication-setup) you enable for your site. If your site doesn't require authentication, the MCP server page only shows the **Admin MCP** tab, but your search MCP server is still accessible at the `/mcp` path of your site URL.
</Note>

<Frame>
<img src="/images/mcp/mcp-server-page-light.png" alt="MCP server page in the dashboard." className="block dark:hidden" />
<img src="/images/mcp/mcp-server-page-dark.png" alt="MCP server page in the dashboard." className="hidden dark:block" />
</Frame>

<Note>
Search MCP servers use the `/mcp` and `/authed/mcp` paths. Other navigation elements cannot use these paths.
</Note>
The `/mcp` and `/authed/mcp` paths are reserved for search MCP servers and cannot be used for other navigation elements.

Check warning on line 83 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L83

In general, use active voice instead of passive voice ('are reserved').

Check warning on line 83 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L83

In general, use active voice instead of passive voice ('be used').

### Discovery endpoint

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

Check warning on line 87 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L87

Use 'AGENTS' instead of 'agents'.

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

Expand Down Expand Up @@ -168,7 +170,7 @@
| `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 read-only and non-destructive with the following annotations:

Check warning on line 173 in ai/model-context-protocol.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/model-context-protocol.mdx#L173

In general, use active voice instead of passive voice ('are read').

- `readOnlyHint: true` — the tool does not modify any state.
- `destructiveHint: false` — the tool has no destructive side effects.
Expand Down
Binary file modified images/mcp/mcp-server-page-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified images/mcp/mcp-server-page-light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading