diff --git a/ai/mintlify-mcp.mdx b/ai/mintlify-mcp.mdx index 727a9edc25..dc9dab777e 100644 --- a/ai/mintlify-mcp.mdx +++ b/ai/mintlify-mcp.mdx @@ -1,50 +1,51 @@ --- -title: "Mintlify MCP" -description: "Let AI tools directly edit your content on Mintlify with the MCP server. Connect Claude, Cursor, or any MCP client to draft, save, and ship doc changes." +title: "Admin Model Context Protocol (MCP) server" +shortTitle: "Admin MCP" +description: "Let AI tools directly edit your content and update settings in your dashboard with the admin MCP server. Connect Claude, Cursor, or any MCP client to draft, save, and ship changes." keywords: ["MCP", "write access", "AI", "editing", "Claude", "Cursor", "branch", "pull request"] --- -## About the Mintlify MCP +## About the admin MCP -The Mintlify MCP server gives AI tools write access to your Mintlify content. Where the [documentation MCP server](/ai/model-context-protocol) lets AI tools read and search your published content, the Mintlify MCP lets them propose changes: edit pages, restructure navigation, update `docs.json`, and open pull requests. +The admin MCP server gives AI tools write access to your Mintlify content and settings. Use it to update content and access your dashboard. With the admin MCP, you can use your preferred AI tools to edit pages, restructure navigation, update `docs.json`, open pull requests, change settings, create workflows, and more. -Connect any MCP client like Claude, Claude Code, or Cursor to the Mintlify MCP to collaborate on your Mintlify content with the same tools you use to write code. When you use the MCP server, all changes happen on a branch and require a pull request to merge. +Connect any MCP client like Claude, Claude Code, or Cursor to the admin MCP server to collaborate on your Mintlify content and settings with the same tools you use to write code. When you use the admin MCP server, all changes happen on a branch and require a pull request to merge. - The Mintlify MCP edits your documentation. Treat it like a developer with commit access. Connect it only from trusted AI tools and review every pull request before merging. + The admin MCP server allows AI tools to access your Mintlify dashboard. Treat it like a coworker with write access. Connect it only from trusted AI tools and review every pull request before merging. -### How the Mintlify MCP differs from the documentation MCP +### How the admin MCP differs from the search MCP -| | Documentation MCP | Mintlify MCP | +| | Admin MCP | Search MCP | | :-- | :-- | :-- | -| **Audience** | Your end users | Your team | -| **Access** | Read and search published pages | Read, edit, restructure, save | -| **Endpoints** | `/mcp` on your site domain | Hosted by Mintlify, scoped to your project | -| **Output** | Search results and page content | Content edits, navigation changes, pull requests | +| **Audience** | Your team | Your end users | +| **Access** | Read, edit, restructure, save, create workflows, manage settings | Read and search published pages | +| **Endpoints** | Hosted by Mintlify, scoped to your project | `/mcp` on your site domain | +| **Output** | Content edits, navigation changes, pull requests, workflow runs | Search results and page content | -## Connect to the Mintlify MCP +## Connect to the admin MCP -Connecting requires an interactive OAuth login against your Mintlify account. The AI tool exchanges that login for a session token scoped to one project. +You must have an interactive OAuth login against your Mintlify account to connect to the admin MCP. AI tools exchange that login for a session token scoped to one project. - + 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings. 2. Click **Add custom connector**. 3. Add the connector - - Name: Mintlify MCP - - URL:  `https://mcp.mintlify.com` + - Name: Admin MCP + - URL: `https://mcp.mintlify.com` 4. Click **Add** and complete the OAuth login. - Click the attachments button (the plus icon), then select your Mintlify MCP server. Claude can now call the Mintlify MCP tools while answering your prompt. + Click the attachments button (the plus icon), then select your admin MCP server. Claude can now call the Mintlify admin MCP tools while answering your prompt. - Add the Mintlify MCP server with the Claude Code CLI: + Add the admin MCP server with the Claude Code CLI: ```bash claude mcp add --transport http mintlify https://mcp.mintlify.com @@ -55,7 +56,7 @@ Connecting requires an interactive OAuth login against your Mintlify account. Th 1. Open the command palette with Command \+ Shift \+ P (Ctrl \+ Shift \+ P on Windows). 2. Search for **Open MCP settings** and click **Add custom MCP**. - 3. In `mcp.json`, add the Mintlify MCP: + 3. In `mcp.json`, add the admin MCP: ```json { @@ -73,7 +74,7 @@ Connecting requires an interactive OAuth login against your Mintlify account. Th ## How a session works -Every Mintlify MCP session binds to a single Git branch. The flow is: +Every admin MCP session binds to a single Git branch. The flow is: @@ -99,7 +100,7 @@ Every Mintlify MCP session binds to a single Git branch. The flow is: Calling `checkout` again during an active session switches the session to the new branch. Use this to abandon an in-progress draft and start fresh without ending the conversation. -## What the Mintlify MCP can do +## What the admin MCP can do ### Content @@ -131,7 +132,7 @@ Every Mintlify MCP session binds to a single Git branch. The flow is: ## Example prompts -After you connect the Mintlify MCP, you can drive it with natural-language prompts. For example: +After you connect the admin MCP, you can drive it with natural-language prompts. For example: - _"Check out a branch called `add-billing-faq` and create a new page under the FAQ group titled 'Billing'. Draft answers for the five questions in this Linear issue."_ - _"Find every page that mentions the deprecated `legacy_token` field and update the example to use `api_key` instead. Save as a PR titled 'docs: replace legacy\_token references'."_ @@ -145,7 +146,7 @@ After you connect the Mintlify MCP, you can drive it with natural-language promp - The Mintlify MCP is powerful enough to rewrite hundreds of pages in a single session. Before merging, read the PR diff and skim the rendered preview. Don't rubber-stamp large changes. + The admin MCP is powerful enough to rewrite hundreds of pages in a single session. Before merging, read the PR diff and skim the rendered preview. Don't rubber-stamp large changes. diff --git a/ai/model-context-protocol.mdx b/ai/model-context-protocol.mdx index 514240dceb..f004017b2d 100644 --- a/ai/model-context-protocol.mdx +++ b/ai/model-context-protocol.mdx @@ -1,74 +1,75 @@ --- -title: "Model Context Protocol (MCP)" -description: "Connect your documentation and API endpoints to AI tools like Claude and Cursor with a hosted Model Context Protocol (MCP) server." -keywords: ["MCP", "AI tools", "Claude", "Cursor"] +title: "Search Model Context Protocol (MCP) server" +shortTitle: "Search MCP" +description: "Connect your content to AI tools like Claude and Cursor with a hosted MCP server for search." +keywords: ["MCP", "AI tools", "Claude", "Cursor", "search"] --- import { PreviewButton } from "/snippets/previewbutton.jsx" ## About MCP servers -The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates an MCP server from your documentation, preparing your content for the broader AI ecosystem. Any MCP client like Claude, Cursor, Goose, or ChatGPT can connect to your documentation. +The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. Mintlify generates a search MCP server for your site, preparing your content for the broader AI ecosystem. Any MCP client like Claude, Cursor, Goose, or ChatGPT can connect to your content. -Your MCP server exposes tools for AI applications to search your documentation and retrieve full page content. Your users must connect your MCP server to their tools. +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. - Looking to let agents edit your content instead of read it? See the [Mintlify MCP server](/ai/mintlify-mcp) for an authenticated MCP server that exposes branching, page editing, navigation, and `docs.json` tools to trusted agents. + 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. ### How MCP servers work -When an AI application connects to your documentation MCP server, it can search your documentation and retrieve full page content directly in response to a user's prompt. This avoids relying on information from training data or generic web searches. Your MCP server provides access to all indexed content on your documentation site. +When an AI application connects to your search MCP server, it can search your content and retrieve full pages in response to a user's prompt. This avoids relying on information from training data or generic web searches. Your search MCP server provides access to all indexed content on your Mintlify site. -- AI applications can proactively search your documentation while generating a response even if not explicitly asked to search your documentation for an answer. -- AI applications determine when to use the available tools based on the context of the conversation and the relevance of your documentation. -- Each tool call happens during the generation process, so the AI application uses up-to-date information from your documentation to generate its response. +- AI applications can proactively search your content while generating a response even if not explicitly asked to search for an answer. +- AI applications determine when to use the available tools based on the context of the conversation and the relevance of your content. +- Each tool call happens during the generation process, so the AI application uses up-to-date information from your site to generate its response. - Some AI tools like Claude support both MCP and skills. MCP gives access to your documentation content, while skills instruct agents how to use that content effectively. They're complementary and connecting your MCP server gives agents access to both. + 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. ### MCP tools -Your MCP server provides two tools that agents can use: +Your search MCP server provides two tools that agents can use: -- **Search**: Searches across your documentation 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 documentation's virtual filesystem using shell-style commands. Use this to retrieve page content, browse the docs structure, or extract specific sections—including batch reads across multiple pages in a single call. +- **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 documentation to find relevant pages, then use the query docs filesystem tool to read the full content of the most relevant results. +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 MCP server also exposes your [skill.md files](/ai/skillmd) as MCP resources. Agents connected to your MCP server can discover and access your skill files without installing them separately. +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 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). +`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). ### Search parameters The MCP search tool supports optional parameters that AI applications use to control and refine search results. -- **`version`**: Filter results to a specific documentation version. For example, `'v0.7'`. Only available when your documentation has multiple versions. Only returns content tagged with the specified version or content available across all versions. -- **`language`**: Filter results to a specific language code. For example, `'en'`, `'zh'`, or `'es'`. Only available when your documentation has multiple languages. Only returns content in the specified language or content available across all languages. +- **`version`**: Filter results to a specific site version. For example, `'v0.7'`. Only available when your site has multiple versions. Only returns content tagged with the specified version or content available across all versions. +- **`language`**: Filter results to a specific language code. For example, `'en'`, `'zh'`, or `'es'`. Only available when your site has multiple languages. Only returns content in the specified language or content available across all languages. AI applications determine when to apply these parameters based on the context of the user's query. For example, if a user asks about a specific API version, the AI application may automatically apply the appropriate filter to provide more relevant results. -### MCP compared to web search +### Search MCP compared to web search -AI tools can search the web, but MCP provides distinct advantages for documentation. +AI tools can search the web, but the search MCP provides distinct advantages. -- **Direct source access**: Web search depends on what search engines have indexed, which may be stale or incomplete. MCP searches your current indexed documentation directly. +- **Direct source access**: Web search depends on what search engines have indexed, which may be stale or incomplete. The search MCP searches your current indexed content directly. - **Integrated workflow**: MCP allows the AI to search during response generation rather than performing a separate web search. -- **No search noise**: SEO and ranking algorithms influence web search results. MCP goes straight to your documentation content. +- **No search noise**: SEO and ranking algorithms influence web search results. MCP goes straight to your content. -## Access your MCP server +## Access your search MCP server -Mintlify generates an MCP server for your documentation and hosts it at the `/mcp` path of your documentation URL. For example, Mintlify's MCP server is available at `https://mintlify.com/docs/mcp`. +Mintlify generates a search MCP server for your site and hosts it at the `/mcp` path of your site URL. For example, Mintlify's search MCP server is available at `https://mintlify.com/docs/mcp`. -* For public documentation, your MCP server is available to anyone. It searches all indexed public pages. -* For documentation with partial authentication, where some pages are public and others require login, you must enable your 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 documentation where all pages require authentication, you must enable your MCP server before it is available to users. Users must authenticate before connecting to your MCP server. Your MCP server searches only the content each user has access to based on their [user groups](/deploy/authentication-setup). +* For public content, your search MCP server is available to anyone. It searches all indexed public pages. +* 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 MCP server URL on the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard. +View and copy your search MCP server URL on the [MCP server page](https://app.mintlify.com/products/mcp) in your dashboard. MCP server page in the dashboard. @@ -76,14 +77,14 @@ View and copy your MCP server URL on the [MCP server page](https://app.mintlify. - Hosted MCP servers use the `/mcp` and `/authed/mcp` paths. Other navigation elements cannot use these paths. + Search MCP servers use the `/mcp` and `/authed/mcp` paths. Other navigation elements cannot use these paths. ### Discovery endpoint -Mintlify hosts a discovery document at `/.well-known/mcp` for agents and tools to locate your MCP server without prior configuration. +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 MCP server: +`GET /.well-known/mcp` returns a JSON document describing your search MCP server: ```json { @@ -120,9 +121,9 @@ For agent-readiness, the same discovery document is also available at `/.well-kn ### Enable authenticated MCP -If your documentation requires authentication, your 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). +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). -If your documentation has partial authentication with both public and protected pages, you have two MCP server endpoints: +If your site has partial authentication with both public and protected pages, you have two search MCP server endpoints: - `/mcp`: Does not require authentication. Returns only public content. Share this with users who need access to public content. - `/authed/mcp`: Always requires authentication. Returns content scoped to each user's permissions based on their [user groups](/deploy/authentication-setup). Share this with users who need access to protected content. @@ -159,7 +160,7 @@ Client credentials authenticate against the `/authed/mcp` endpoint and return al 4. Copy the **client ID** and **client secret**. The client secret is only shown once. You cannot retrieve it later. - Send a POST request to your MCP server's token endpoint with your client ID and secret. Your token endpoint is at the `/authed/mcp/oauth/token` path of your documentation URL. + Send a POST request to your MCP server's token endpoint with your client ID and secret. Your token endpoint is at the `/authed/mcp/oauth/token` path of your site's URL. ```bash cURL @@ -237,18 +238,18 @@ To protect availability, Mintlify applies rate limits to MCP servers. | Scope | Limit | Description | | :---- | :---- | :---------- | | Per user (IP address) | 5,000 requests per hour | Limits how frequently a single user can query your MCP server configuration. | -| Search per documentation site (domain) | 10,000 requests per hour | Limits total search tool calls across all users of your MCP server. | -| Query docs filesystem per documentation site (domain) | 10,000 requests per hour | Limits total query docs filesystem tool calls across all users of your MCP server. | -| Authenticated search per documentation site (domain) | 5,000 requests per hour | Limits total authenticated search tool calls across all users of your MCP server. | -| Authenticated query docs filesystem per documentation site (domain) | 5,000 requests per hour | Limits total authenticated query docs filesystem tool calls across all users of your MCP server. | +| Search per site (domain) | 10,000 requests per hour | Limits total search tool calls across all users of your MCP server. | +| Query docs filesystem per site (domain) | 10,000 requests per hour | Limits total query docs filesystem tool calls across all users of your MCP server. | +| Authenticated search per site (domain) | 5,000 requests per hour | Limits total authenticated search tool calls across all users of your MCP server. | +| Authenticated query docs filesystem per site (domain) | 5,000 requests per hour | Limits total authenticated query docs filesystem tool calls across all users of your MCP server. | ## Content filtering and indexing -Your MCP server searches content that Mintlify indexes from your documentation repository. File processing and search indexing control what content is available through your MCP server. +Your MCP server searches content that Mintlify indexes from your project repository. File processing and search indexing control what content is available through your MCP server. -For documentation that requires authentication, your MCP server indexes [public pages](/deploy/authentication-setup#make-pages-public) and any pages an authenticated user has permission to access based on their [user groups](/deploy/authentication-setup#restrict-pages-to-specific-user-groups). +For sites that require authentication, your MCP server indexes [public pages](/deploy/authentication-setup#make-pages-public) and any pages an authenticated user has permission to access based on their [user groups](/deploy/authentication-setup#restrict-pages-to-specific-user-groups). -For documentation with partial authentication, unauthenticated users can search public pages. Authenticated users can search public pages and any pages they have permission to access based on their user groups. +For sites with partial authentication, unauthenticated users can search public pages. Authenticated users can search public pages and any pages they have permission to access based on their user groups. ### File processing with `.mintignore` @@ -282,13 +283,13 @@ Your users must connect your MCP server to their preferred AI tools. 1. Make your MCP server URL publicly available. 2. Users copy your MCP server URL and add it to their tools. -3. Users access your documentation through their tools. +3. Users access your content through their tools. These are some of the ways you can help your users connect to your MCP server: - Add options in the [contextual menu](/ai/contextual-menu) for your users to connect to your MCP server from any page of your documentation. + Add options in the [contextual menu](/ai/contextual-menu) for your users to connect to your MCP server from any page on your site. | Option | Identifier | Description | | :----- | :--------- | :---------- |