Migrate from Mintlify to Pathfinder

Your Markdown docs are already structured for it. This guide takes about 15 minutes and gives you full ownership of your knowledge infrastructure.

Why Migrate

Index more than just docs. Mintlify only indexes your published documentation. Pathfinder indexes docs, Notion pages, Slack threads, and Discord forums — your agents search everything your team knows, not just what's published.
Own your infrastructure. No vendor lock-in, no per-seat pricing, no surprise deprecations. Your docs live in your repo, your search runs on your Postgres.
Both retrieval paradigms. Mintlify's ChromaFS replaced RAG with filesystem access. Pathfinder composes both — agents pick the right tool for each sub-task.
Agentic features out of the box. Session state, vector grep, writable workspaces, cross-source related commands, and telemetry — all config-driven.
Zero-infra option. Start with bash-only tools (no database, no API keys) and add RAG when you're ready. Mintlify's ChromaFS always requires Chroma + Redis.

What You Gain

🔍

Beyond Just Docs

Mintlify indexes your docs. Pathfinder indexes your docs, Notion wikis, Slack threads, and Discord forums — all in one server. Your agents search everything your team knows, not just what's published.

🧭

Session State

Agents cd into directories and stay there across commands. No more repeating full paths every tool call.

⚡

Vector Grep & qmd

When grep misses, Pathfinder suggests qmd — a semantic search command that finds docs by meaning, not just text matches.

📝

Writable Workspace

Agents save notes, grep results, and intermediate files to /workspace/ during a session.

🔗

Cross-Source Related

Run related /docs/auth.mdx to discover semantically similar files across all sources.

📊

Feedback Collection

Define collect tools with YAML schemas. Agents report search quality, broken links, or anything you define.

🚀

Zero-Infra Start

Bash-only mode needs no database or API keys. Add RAG later with a config change — no code edits.

Concept Mapping

How Mintlify concepts translate to Pathfinder:

Mintlify	Pathfinder	Notes
`mint.json`	`pathfinder.yaml`	Config file — YAML instead of JSON
Hosted docs site	MCP server (self-hosted)	Agents consume tools, not rendered pages
ChromaFS collection	Source (type: markdown)	Multiple sources supported
ChromaFS search	Search tool (type: search)	pgvector instead of Chroma
ChromaFS find/grep/cat	Bash tool (type: bash)	Same commands, plus session state
Chroma embeddings	OpenAI, Ollama, or local embeddings	Configurable model and dimensions
Chroma + Redis infra	PostgreSQL + pgvector	Single database, no Redis needed
Manual reingestion	Webhook auto-reindex	GitHub push triggers targeted reindex
Docs only	Multiple source types	Markdown, HTML, Notion, Slack, Discord — index everything in one server

Migration Walkthrough

Install Pathfinder

CLI:

$ npx @copilotkit/pathfinder init
$ npx @copilotkit/pathfinder serve

Docker:

$ docker pull ghcr.io/copilotkit/pathfinder

See full setup guide for detailed instructions.

Map your docs source

Open pathfinder.yaml and add your docs repo as a source. If your Mintlify docs live at docs/ in your repo:

sources:
  - name: docs
    type: markdown
    repo: https://github.com/your-org/your-repo.git
    path: docs/
    file_patterns: ["**/*.mdx", "**/*.md"]
    chunk:
      target_tokens: 600
      overlap_tokens: 50

Configure tools

Define how agents access your docs. You can use search (RAG), bash (filesystem), or both:

tools:
  # Semantic search — like ChromaFS search but with pgvector
  - name: search-docs
    type: search
    source: docs
    default_limit: 5

  # Filesystem exploration — like ChromaFS find/grep/cat
  - name: explore-docs
    type: bash
    sources: [docs]
    bash:
      session_state: true
      grep_strategy: hybrid

Set environment variables

Create a .env file with your credentials:

# Required for RAG search tools
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://user:pass@localhost:5432/pathfinder

# Optional: for private repos
GITHUB_TOKEN=ghp_...

# Optional: for webhook auto-reindex
GITHUB_WEBHOOK_SECRET=your-secret

If you only use bash tools (no search), you can skip OPENAI_API_KEY and DATABASE_URL entirely.

Start the server

$ docker compose up

This starts Pathfinder and PostgreSQL. The first boot automatically indexes your sources.

Connect your AI agent

Point your agent's MCP config at Pathfinder:

{
  "mcpServers": {
    "docs": { "url": "http://localhost:3001/mcp" }
  }
}

Your agent now has access to both search and bash tools.

Set up auto-reindex (optional)

Add webhook config so docs reindex automatically when you push:

webhook:
  repo_sources:
    "your-org/your-repo": [docs]
  path_triggers:
    docs: ["docs/"]

Then add a GitHub webhook pointing to https://your-server/webhooks/github with the push event.

What's Different

Pathfinder is not a drop-in replacement for Mintlify's full platform. Here's what it doesn't do:

No hosted docs site

Pathfinder is an MCP server, not a documentation hosting platform. Your rendered docs site (if you need one) stays wherever it is — Mintlify, Docusaurus, GitBook, etc.

No built-in UI

There's no web dashboard for browsing search results or managing content. Pathfinder is designed for agent consumption via MCP, not human browsing.

Self-hosted only

You run the infrastructure. Docker Compose makes this straightforward, but there's no managed cloud offering (yet). You need PostgreSQL and optionally an OpenAI API key.

Analytics dashboard included

Pathfinder includes a built-in analytics dashboard at /analytics with query logging, top queries, empty result tracking, and latency metrics. Enable it with analytics.enabled: true in your config.

← Back to Pathfinder