Connect Mintlify to ChatGPT: Manage Projects and Reader Insights

If you are responsible for maintaining a technical documentation site, you want to connect Mintlify to ChatGPT so your DevRel engineers and AI agents can analyze reader feedback, discover documentation gaps, and trigger deployments automatically. (If your team uses Claude, check out our guide on connecting Mintlify to Claude or explore our broader architectural overview on connecting Mintlify to AI Agents). Here is exactly how to do it using a Model Context Protocol (MCP) server.

Giving a Large Language Model (LLM) read and write access to your documentation infrastructure is an engineering challenge. You either spend weeks building, hosting, and maintaining a custom MCP server to translate LLM tool calls into Mintlify REST API requests, or you use a managed infrastructure layer that handles the boilerplate for you.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Mintlify, connect it natively to ChatGPT, and execute complex documentation workflows using natural language.

The Engineering Reality of the Mintlify API

A custom MCP server is a self-hosted integration layer. While Anthropic's open MCP standard provides a predictable way for models to discover tools over JSON-RPC, the reality of implementing it against vendor APIs is painful. If you decide to build a custom MCP server for Mintlify, you own the entire API lifecycle.

Here are the specific integration challenges that break standard CRUD assumptions when working with Mintlify:

Asynchronous Deployments and State Polling Mintlify's deployment architecture is asynchronous. When you trigger a project update, the API does not keep the connection open until the build finishes. It immediately returns a statusId. If an LLM is asked to "deploy the latest docs and tell me when it's live," it cannot simply call one endpoint. Your system must equip the LLM with a secondary polling tool and explicitly instruct it to query that status endpoint repeatedly until the status returns success or failure.

Analytics Data Aggregation and Schema Complexity Extracting insights from Mintlify is not a standard object retrieval. The analytics endpoints - such as page views, unique visitors, and search queries - return heavily aggregated, time-series data. Your MCP server must properly map these schemas so the LLM understands how to filter by date ranges, group by page paths, and interpret the structured analytics arrays without hallucinating trends.

Handling Rate Limits and 429 Errors API consumers often expect integration platforms to silently absorb rate limits. We take a different approach. When the Mintlify API returns an HTTP 429 Too Many Requests, Truto does not retry, throttle, or apply backoff logic. Truto passes that error directly back to the caller. We normalize the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification. The caller - your AI agent or client framework - is entirely responsible for interpreting these headers and executing its own retry and backoff logic. If your custom server fails to handle this gracefully, the LLM will assume the tool call succeeded when it actually dropped the payload.

Creating the Mintlify MCP Server

Instead of writing and hosting a custom Node.js or Python server to map Mintlify's endpoints to the MCP protocol, you can generate a managed MCP server dynamically. Truto translates Mintlify's OpenAPI resources and documentation records into dynamic MCP tool definitions.

Every MCP server is scoped to a single integrated account and protected by a cryptographic token. You can create this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

1. Log into your Truto dashboard and navigate to the integrated account page for your active Mintlify connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods, tags, and expiration).
5. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4....

Method 2: Via the API

For platform teams automating infrastructure, you can generate the MCP server programmatically. The API validates the configuration, generates a secure hashed token, and provisions the JSON-RPC endpoint.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mintlify Production Deployer",
    "config": {
      "methods": ["read", "write"],
      "tags": ["analytics", "deployments"]
    }
  }'

The response returns the URL that you will provide to ChatGPT:

{
  "id": "abc-123",
  "name": "Mintlify Production Deployer",
  "config": { "methods": ["read", "write"], "tags": ["analytics", "deployments"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to ChatGPT

Once you have your Truto MCP server URL, you must register it with your AI client. ChatGPT and other MCP-compatible clients communicate with this URL via HTTP POST using JSON-RPC 2.0 messages.

Method A: Via the ChatGPT UI

If you are using the ChatGPT desktop or web interface (requires a Pro, Plus, Business, Enterprise, or Education account):

1. In ChatGPT, navigate to Settings -> Apps -> Advanced settings.
2. Enable Developer mode (MCP support is gated behind this flag).
3. Under MCP servers / Custom connectors, click to add a new server.
4. Set the Name to something descriptive like "Mintlify Analytics".
5. Paste the Server URL you copied from Truto.
6. Save the configuration. ChatGPT will immediately perform the MCP handshake (initialize), request the tool list, and make the Mintlify tools available in your conversation context.

Method B: Via Manual Config File (Local Agents & CLI)

If you are running a custom agent framework, local LLM interface, or a developer tool like Cursor that utilizes MCP configuration files, you configure the server using a Server-Sent Events (SSE) transport adapter.

Add the following block to your mcp.json or equivalent configuration file:

{
  "mcpServers": {
    "mintlify-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

This instructs the local MCP client to proxy requests to the remote Truto URL.

Mintlify Hero Tools for ChatGPT

When ChatGPT connects to the server, Truto dynamically generates the tool definitions from Mintlify's API documentation. Here are the most critical, high-leverage tools available for documentation management.

Queue a Project Update

Tool Name: create_a_mintlify_project_update

This tool is used to trigger a deployment of a Mintlify project from its configured repository branch. It is an asynchronous operation that returns a statusId rather than a finished build payload.

"I just merged a PR to the main branch for our API docs. Please trigger a Mintlify project update and give me the status ID so we can track it."

Get Deployment Status

Tool Name: get_single_mintlify_project_update_status_by_id

Because updates are asynchronous, the LLM must use this tool to poll the deployment status. It requires the id returned from the project update tool and provides detailed logs, a summary, and the current state (e.g., in_progress, success, failure).

"Using the status ID you just received, check if the Mintlify deployment has finished. If it failed, summarize the error logs."

List Search Queries

Tool Name: list_all_mintlify_search_queries

This tool fetches the actual search terms users are entering into your documentation site. It is critical for identifying content gaps. DevRel teams use this to figure out what developers are searching for but failing to find.

"Fetch the search queries for our Mintlify project from the last 7 days. Identify the top 5 queries that resulted in zero clicks, indicating a gap in our documentation."

List Reader Feedback

Tool Name: list_all_mintlify_feedback

Mintlify allows readers to upvote, downvote, and leave comments on specific pages. This tool retrieves that feedback array from the analytics dataset, enabling the LLM to summarize sentiment or flag inaccurate pages.

"Pull the reader feedback from our Mintlify project. Find all the pages that received a negative rating this week and summarize the user comments so I know what to rewrite."

List Page Views

Tool Name: list_all_mintlify_page_views

Retrieves page view analytics for your documentation. This tool allows the LLM to cross-reference high-traffic pages against negative feedback, ensuring you prioritize fixes for your most visible content.

"List the top 10 most viewed pages on our Mintlify docs. Cross-reference these with the feedback data to see if our most popular pages are causing user frustration."

Create an Agent Job

Tool Name: create_a_mintlify_agent_job

Mintlify provides AI assistant capabilities to help users navigate docs. This tool programmatically creates a job context for the agent within a specific project, which is useful when testing bot responses or automating support escalations.

"Create a new Mintlify agent job for our enterprise docs project so we can test the AI assistant's response to the new rate limiting rules we just published."

To view the complete inventory of available Mintlify endpoints, parameters, and schemas, visit the Mintlify integration page.

Workflows in Action

Providing individual tools to an LLM is useful, but the real power of MCP is multi-step orchestration. Here is how specific personas use ChatGPT and Mintlify tools to automate complex tasks.

Scenario 1: The Content Gap Analysis & Update

Persona: Developer Relations Engineer

DevRel engineers spend hours manually checking analytics to figure out what documentation is missing, writing the missing docs, and deploying the updates. An AI agent can compress this feedback loop.

"Analyze our Mintlify search queries to find the top 3 terms that result in no clicks. Then, check the reader feedback for any comments mentioning those terms. Finally, outline a new documentation page addressing these gaps and trigger a Mintlify project update to pull in my latest branch."

Execution Steps:

1. list_all_mintlify_search_queries: ChatGPT retrieves the raw search data, applying logic to filter for high-volume, zero-click terms (e.g., "webhooks retry policy").
2. list_all_mintlify_feedback: ChatGPT fetches reader feedback and text-matches against the failed search terms to gather specific complaints.
3. Reasoning Engine: ChatGPT synthesizes the data and generates an outline for the missing "Webhooks Retry Policy" page.
4. create_a_mintlify_project_update: After the engineer confirms the PR is merged, ChatGPT calls the deployment tool and retrieves the statusId.

Scenario 2: The Asynchronous Deployment Monitor

Persona: DevOps / Technical Writer

When massive doc refactors occur, deployments can fail due to broken MDX formatting or missing components. ChatGPT can act as a deployment monitor, triggering the build and polling until completion.

"Trigger a Mintlify project update for the 'v2-api-refactor' branch. Check the status immediately. If it is in_progress, wait 10 seconds and check again. Keep checking until it succeeds or fails. If it fails, extract the exact syntax error from the logs."

Execution Steps:

1. create_a_mintlify_project_preview: ChatGPT queues the preview deployment for the specific branch and stores the statusId.
2. get_single_mintlify_project_update_status_by_id: ChatGPT queries the status endpoint.
3. Looping Logic: The LLM observes the in_progress state, yields, and recursively calls the status tool again.
4. Analysis: Once the status transitions to failure, ChatGPT parses the returned logs array, identifies the MDX syntax error (e.g., "unclosed JSX tag on line 42"), and presents the fix to the user.

Security and Access Control

Giving an LLM write access to your production documentation infrastructure requires strict access controls. If a user prompt is maliciously crafted, you do not want the model deleting configurations or deploying unauthorized branches. Truto's MCP servers provide several layers of security:

• Method Filtering: You can restrict the MCP server entirely to read-only operations. By setting methods: ["read"] during server creation, Truto will strip out all create, update, and delete tools. The LLM will physically not have the tools available to trigger deployments, limiting it strictly to analytics and feedback readouts.
• Tag Filtering: If you only want the LLM to access analytics data and not project metadata, you can apply tag filters (e.g., tags: ["analytics"]). Truto evaluates the tool definitions and drops any endpoints that do not match the approved tags.
• Time-to-Live Expiration (expires_at): You can set an exact ISO datetime for the MCP server to self-destruct. This is critical when giving a contractor or temporary AI agent access to your docs environment. Once the timestamp passes, the database record and KV store entries are automatically purged.
• Secondary Authentication (require_api_token_auth): By default, possessing the MCP server URL is enough to connect. If you enable this flag, the client must also pass a valid Truto API token in the Authorization header. This ensures that even if the MCP URL leaks in a log file, the connection will fail without the secondary credential.

Wrapping Up

Building an integration layer between an LLM and Mintlify requires more than just formatting JSON. You have to handle asynchronous deployment tracking, parse complex analytics arrays, and strictly enforce the IETF rate limit headers that Mintlify returns.

Instead of wasting engineering cycles building and maintaining a custom proxy server to translate these API paradigms into MCP JSON-RPC messages, you can generate a fully managed server using Truto. This allows your team to focus entirely on prompt engineering, AI agent orchestration, and improving your documentation experience, rather than debugging token refreshes and pagination loops.