Use Mintlify as a knowledge graph for your codebase

A codebase knowledge graph is a Mintlify project that describes your code: what each repository does, what it exposes, and how repositories depend on each other. Agents query it through MCP before they change code. You don’t need existing docs or a migration. Setup takes three steps:

Generate the initial knowledge graph with the Mintlify agent or your own coding agent.
Set up automations to keep it current.
Use the knowledge graph through MCP.

The repositories, pull requests, and answers in the examples on this page are sample data.

Prerequisites

A Mintlify project connected to a Git repository. This hub repository holds the knowledge graph and can start empty. See the Quickstart.
The Mintlify GitHub App installed on the hub repository and on every source repository you want to document.
An Enterprise plan for custom automations.
Authentication on the project, so only your team can read the knowledge graph and connect to its MCP server. Without authentication, anyone can read pages that describe your internal code.
The Mintlify agent, or a coding agent such as Claude Code, Codex, or Cursor.

Plan the structure

Put every repository in one hub project, so agents query one MCP server and pages can link across repositories. Give each repository its own group, plus an overview section.

docs.json

{
  "navigation": {
    "groups": [
      {
        "group": "Overview",
        "pages": ["index", "architecture", "glossary"]
      },
      {
        "group": "Web app",
        "pages": ["repos/web-app/index", "repos/web-app/local-development", "repos/web-app/routing"]
      },
      {
        "group": "API service",
        "pages": ["repos/api-service/index", "repos/api-service/endpoints", "repos/api-service/data-model"]
      },
      {
        "group": "API gateway",
        "pages": ["repos/api-gateway/index", "repos/api-gateway/auth"]
      }
    ]
  }
}

Each repository section should cover what an agent needs before it changes code:

What the repository does and who owns it
The endpoints or events it exposes
What it calls and what calls it
Its key data models
How to run and test it

Start with a few representative repositories, such as one frontend, one backend, and one shared service, before you add the rest.

Step 1: Generate the initial knowledge graph

Have an agent read your source code and write the first pages into the hub repository. Use the Mintlify agent, or clone the repositories and run your own coding agent.

Mintlify agent
Clone and push

The Mintlify agent reads any repository with the Mintlify GitHub App installed, so you don’t clone anything.

Generate documentation for one repository

Open the agent in your dashboard or Slack and name the source repository, the target folder, and the pages to write.

Example prompt

Read the source code in the your-org/api-service repository and write
documentation for it in repos/api-service/.

Create these pages:
- index.mdx: what the service does, who owns it, and how it fits into the
  rest of the system
- endpoints.mdx: every HTTP endpoint with method, path, parameters, and
  response shape, based on the route definitions
- data-model.mdx: the main models and database tables
- local-development.mdx: how to install, run, and test the service

For each page, list the other repositories this service calls or is called
by, and link to their pages under repos/.

Only document what you can confirm from the code. If something is unclear,
leave a TODO comment instead of guessing.

Add the new pages to docs.json in a group named "API service".

The agent opens a pull request in the hub repository. Review it and fix anything the agent got wrong.

Repeat for each repository

Repeat for your other repositories, then ask the agent for the overview pages.

Example prompt

Read every page under repos/ and write architecture.mdx. Describe how the
repositories depend on each other, which services call which, and how a
request moves through the system. Link to the repository pages for details.

Merge the pull requests

When the pull requests merge, Mintlify deploys the knowledge graph and indexes it for search and MCP.

Run Claude Code, Codex, or Cursor on local clones, then push the pages to the hub repository.

Set up your coding agent

Clone the hub and source repositories into one parent directory.

mkdir knowledge-graph && cd knowledge-graph
git clone https://github.com/your-org/docs-hub.git
git clone https://github.com/your-org/web-app.git
git clone https://github.com/your-org/api-service.git
git clone https://github.com/your-org/api-gateway.git

Run mint agent setup with --global to install the Mintlify skill and connect the admin MCP server for your user account. Without --global, the command configures only the hub repository, and an agent you start in the parent directory doesn’t load that configuration.

mint agent setup --global

Generate documentation for one repository

Start your agent in the parent directory and name the source repository, the target folder, and the pages to write.

Example prompt

Read the source code in ../api-service and write documentation for it in
docs-hub/repos/api-service/.

Create these pages:
- index.mdx: what the service does, who owns it, and how it fits into the
  rest of the system
- endpoints.mdx: every HTTP endpoint with method, path, parameters, and
  response shape, based on the route definitions
- data-model.mdx: the main models and database tables
- local-development.mdx: how to install, run, and test the service

For each page, list the other repositories this service calls or is called
by, and link to their pages under docs-hub/repos/.

Only document what you can confirm from the code. If something is unclear,
leave a TODO comment instead of guessing.

Add the new pages to docs-hub/docs.json in a group named "API service".

Review the output, fix anything the agent got wrong, and run mint dev from the hub repository to preview the pages.

Repeat for each repository

Repeat for your other repositories, then ask the agent for the overview pages.

Example prompt

Read every page under docs-hub/repos/ and write docs-hub/architecture.mdx.
Describe how the repositories depend on each other, which services call
which, and how a request moves through the system. Link to the repository
pages for details.

Push to the hub repository

Commit the pages, push them to the hub repository, and open a pull request. When it merges, Mintlify deploys the knowledge graph and indexes it for search and MCP.

git checkout -b initial-knowledge-graph
git add repos architecture.mdx docs.json
git commit -m "Add initial knowledge graph"
git push -u origin initial-knowledge-graph

Save the prompts that worked as a custom skill or an AGENTS.md file in the hub repository. Anyone adding a new repository later gets the same page structure.

Step 2: Keep the knowledge graph current

Create a custom automation with a code change trigger so the agent updates the hub whenever a pull request merges in a source repository.

Create the automation

Open your Automations settings.
Click New automation.
Select the Code change trigger.
Click Add repo for each source repository you documented in step 1. One automation can listen to up to 50 repositories.

Filter the trigger

On each repository card, click Show advanced options. Set Listening to changes in to source paths such as src/**, and add bot accounts to Exclude author. See Filter code change triggers.

Write the instructions

Tell the agent how repositories map to hub pages and what to change.

Example instructions

1. Read the merged pull request diff from the trigger repository.
2. Find the matching folder under /repos/ in this project. The folder name
   matches the repository name.
3. Identify changes to endpoints, events, data models, dependencies on
   other repositories, or setup steps.
4. Update the affected pages in that folder. If the change affects how
   repositories depend on each other, also update /architecture.mdx.
5. If the pull request doesn't change anything the documentation covers,
   make no changes.
6. Open a pull request that lists the pages you changed and links to the
   source pull request.

Choose an update mode

Leave Update and merge changes off at first. The agent then opens a pull request and assigns the source change’s authors as reviewers. When the agent’s pull requests stop needing edits, turn on Update and merge changes. If your deploy branch has branch protection, see Configure automerge.

Test the automation

Save and run it manually, then check the run history and refine the instructions.

This simulator uses an automation that listens to src/** in the three example repositories and excludes dependabot[bot]. To add a repository later, generate its pages as in step 1, then add it to the trigger. Each run that updates the hub uses credits, and runs that change nothing are free. For busy repositories, a schedule trigger batches many merges into one run. See Control credit usage.

The estimate assumes every merge changes documented code, so actual usage is likely lower.

Step 3: Use the knowledge graph through MCP

Every project has a hosted search MCP server. Because the knowledge graph requires authentication, connect your agents to the /authed/mcp path of your site URL. The first time an agent connects, you sign in with the same credentials you use for the site, and the agent reads only the pages that your user groups can access. See Enable authenticated MCP.

Claude Code
Codex
Cursor

claude mcp add --transport http knowledge-graph https://docs.example.com/authed/mcp

codex mcp add knowledge-graph --url https://docs.example.com/authed/mcp

Add the server to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects.

.cursor/mcp.json

{
  "mcpServers": {
    "knowledge-graph": {
      "url": "https://docs.example.com/authed/mcp"
    }
  }
}

See Use your MCP server for other clients. To check the connection, ask your agent how to run one of your repositories locally. Confirm that the agent searches the knowledge-graph server and answers from its pages. To have agents search the knowledge graph on their own, add a line to the CLAUDE.md, AGENTS.md, or Cursor rules file in each source repository.

AGENTS.md

Before changing code that calls another service or repository, search the
knowledge-graph MCP server for that service. Use its documented endpoints,
data models, and conventions instead of guessing.

Here’s how an agent uses the MCP tools to answer questions about your code: When an agent finds an incorrect page, it can report the page with the feedback tool. Reports appear in your feedback dashboard.

Next steps

Automations

Learn about trigger types, update modes, and usage limits.

Search MCP server

Configure indexing, authentication, and client credentials for your MCP server.

Skills

Teach agents how to use your knowledge graph with skill files.

Authentication

Restrict the knowledge graph to your team.

Overview

AI

API docs

Best practices

Git

Use cases

Use Mintlify as a knowledge graph for your codebase

Prerequisites

Plan the structure

Step 1: Generate the initial knowledge graph

Step 2: Keep the knowledge graph current

Step 3: Use the knowledge graph through MCP

Next steps

Automations

Search MCP server

Skills

Authentication

​Prerequisites

​Plan the structure

​Step 1: Generate the initial knowledge graph

​Step 2: Keep the knowledge graph current

​Step 3: Use the knowledge graph through MCP

​Next steps

Automations

Search MCP server

Skills

Authentication

Prerequisites

Plan the structure

Step 1: Generate the initial knowledge graph

Step 2: Keep the knowledge graph current

Step 3: Use the knowledge graph through MCP

Next steps