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 docs retrieval infrastructure.

Why Migrate

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.

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

Migration Walkthrough

Clone Pathfinder

$ git clone https://github.com/CopilotKit/pathfinder.git
$ cd pathfinder
$ cp pathfinder.example.yaml pathfinder.yaml

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 You Gain

🧭

Session State

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

⚡

Vector Grep

When grep misses, semantic search fills the gaps. Three-pass deduplication gives clean results.

📝

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.

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.

No analytics dashboard

Telemetry data (file access patterns, grep misses) goes to the database but there's no built-in visualization. Query it directly or build your own dashboard.

← Back to Pathfinder