Overview

Documint can run entirely on your own infrastructure. The documint-mcp package includes three entry points:

CommandPurposeDefault port
documint-serverREST API control plane8000
documint-mcpMCP server for AI agentsstdio / 8100
documintCLI for scanning, patching, publishing--

In local mode, the API uses SQLite and runs drift detection inline (no Redis or worker queue required).


Quick start

1. Install

bash
pip install documint-mcp

Requires Python 3.11 or later.

2. Start the API

bash
documint-server

The server starts on http://127.0.0.1:8000 with SQLite storage at ./documint.db. In local mode, authentication is disabled from localhost, the database schema is created automatically, and a default workspace is bootstrapped.

3. Verify

bash
curl http://127.0.0.1:8000/health
json
{
  "status": "healthy",
  "project_id": "documint-self",
  "repo_root": "/path/to/your/project",
  "cache": { "memory_cache": { "size": 0 } },
  "runtime": { "deployment_provider": "local" }
}

4. Connect the MCP server

Point the MCP server at your local API:

bash
DOCUMINT_API_URL=http://127.0.0.1:8000 documint-mcp

Or configure your IDE (see MCP Reference for Claude Desktop, Cursor, Windsurf, and Claude Code setup):

json
{
  "mcpServers": {
    "documint": {
      "command": "uvx",
      "args": ["documint-mcp"],
      "env": {
        "DOCUMINT_API_URL": "http://127.0.0.1:8000",
        "DOCUMINT_API_KEY": "any_value"
      }
    }
  }
}

Note: In local debug mode, any value works for DOCUMINT_API_KEY. For production, create a real token via the API.


Environment variables

API server (documint-server)

VariableDefaultDescription
HOST127.0.0.1Bind address
PORT8000Bind port
DEBUGfalseEnable debug mode (disables auth from localhost, enables Swagger UI at /docs)
DATABASE_URLsqlite:///./documint.dbDatabase connection string
REDIS_URLredis://localhost:6379/0Redis connection URL (optional in local mode)
AUTH_TOKEN / DOCUMINT_AUTH_TOKEN--Service bearer token for API access
SECRET_KEYrandomSecret for session and token signing
LOG_LEVELINFOStructured logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
REPO_ROOTauto-detectedPath to the repository root
CACHE_TTL3600Default cache TTL in seconds (60-86400)
MAX_FILE_SIZE10485760Maximum file size in bytes (10 MB)
RATE_LIMIT_REQUESTS120Rate limit requests per minute

Schema and bootstrap

VariableDefaultDescription
DOCUMINT_AUTO_CREATE_SCHEMAtrue (local)Create database tables on startup
DOCUMINT_AUTO_BOOTSTRAP_DEFAULTStrue (local)Seed default workspace and project
DOCUMINT_JOB_EXECUTION_MODEinline (local) / queue (production)inline runs jobs synchronously; queue uses arq workers
DOCUMINT_ENVIRONMENTauto-detectedlocal, test, or production environment name

AI providers (for patch generation)

VariableDescription
ANTHROPIC_API_KEYAnthropic API key for Claude-based patch drafting
OPENROUTER_API_KEYOpenRouter API key for fallback patch drafting
HF_API_TOKENHugging Face API token for summarization
HF_PRIMARY_MODELPrimary HF model for patch drafting
HF_FAST_MODELFast HF model for change triage

Note: AI providers are optional. Drift detection works without them. Patch generation falls back to deterministic mode when no provider is configured.

GitHub App (for PR automation)

VariableDescription
GITHUB_APP_IDGitHub App identifier
GITHUB_APP_PRIVATE_KEYPEM-encoded private key
GITHUB_WEBHOOK_SECRETWebhook signature secret
GITHUB_API_URLGitHub API base URL (default: https://api.github.com)

Clerk authentication (optional)

VariableDescription
CLERK_JWKS_URLClerk JWKS endpoint for JWT verification
CLERK_ISSUERExpected JWT issuer
CLERK_AUDIENCEExpected JWT audience (optional)

MCP server (documint-mcp)

VariableDefaultDescription
DOCUMINT_API_KEY--API key for the Documint REST API
DOCUMINT_API_URLhttps://api-production-285b.up.railway.appBase URL of the Documint API
DOCUMINT_MCP_TRANSPORTstdioTransport: stdio, sse, streamable-http
DOCUMINT_MCP_HOST127.0.0.1Bind host for SSE/HTTP transports
DOCUMINT_MCP_PORT8100Bind port for SSE/HTTP transports
DOCUMINT_DOCS_ROOT.Root for local .mint file lookups

Database setup

SQLite (development)

The default. No configuration needed. The database file is created at ./documint.db on first startup.

bash
# Explicit
DATABASE_URL=sqlite:///./documint.db documint-server

PostgreSQL (production)

For production deployments, use PostgreSQL:

bash
DATABASE_URL=postgresql://user:pass@localhost:5432/documint documint-server

Create the database first:

bash
createdb documint

Important: In production (DOCUMINT_ENVIRONMENT is not local or test), the API validates that PostgreSQL is used and rejects SQLite.


Docker setup

Using the official Dockerfile

Build and run the Documint API from the repository:

bash
docker build -t documint .
docker run -p 8000:8000 \
  -e DATABASE_URL=sqlite:///app/documint.db \
  -e DEBUG=true \
  documint

Docker Compose

A minimal setup with PostgreSQL and Redis:

yaml
version: "3.8"
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://documint:documint@db:5432/documint
      REDIS_URL: redis://redis:6379/0
      HOST: "0.0.0.0"
      PORT: "8000"
      DEBUG: "false"
      DOCUMINT_AUTO_CREATE_SCHEMA: "true"
      DOCUMINT_JOB_EXECUTION_MODE: inline
    depends_on:
      - db
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: documint
      POSTGRES_PASSWORD: documint
      POSTGRES_DB: documint
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

Start the stack:

bash
docker compose up -d

Production considerations

The production Docker image:

  • Runs as a non-root user (appuser)
  • Includes a health check against /health
  • Exposes port 8000
  • Sets PYTHONUNBUFFERED=1 and PYTHONDONTWRITEBYTECODE=1
  • Uses the scripts/entrypoint.sh script as the default command

For production deployments, ensure:

  • DEBUG is false
  • DOCUMINT_AUTO_CREATE_SCHEMA is false (run migrations with alembic instead)
  • DOCUMINT_AUTO_BOOTSTRAP_DEFAULTS is false
  • DOCUMINT_JOB_EXECUTION_MODE is queue with an arq worker running
  • PostgreSQL and Redis are available
  • GitHub App credentials and Clerk JWT verification are configured

Running the MCP server alongside the API

For a complete local setup, run both the API and MCP server:

bash
# Terminal 1: Start the API
documint-server

# Terminal 2: Start the MCP server with SSE transport
DOCUMINT_API_URL=http://127.0.0.1:8000 \
DOCUMINT_MCP_TRANSPORT=sse \
DOCUMINT_MCP_PORT=8100 \
documint-mcp

Or embed the MCP server inside the API process:

python
from documint_mcp.server import create_app
from documint_mcp.mcp_server import mount_on_fastapi

app = create_app()
mount_on_fastapi(app, "/mcp-sse")

CLI commands

The documint CLI mirrors the control plane:

bash
documint login              # Authenticate with the API
documint workspaces list    # List workspaces
documint projects list      # List projects
documint projects create    # Create a new project
documint scan               # Scan for documentation drift
documint drift              # Show drift findings
documint patches propose    # Generate a patch
documint publish            # Publish docs
documint traces show        # Explain artifact traceability

Upgrading

bash
pip install --upgrade documint-mcp

Database migrations are managed with alembic. After upgrading:

bash
# For production (auto_create_schema disabled)
alembic upgrade head

# For local development (auto_create_schema enabled)
# Tables are created/updated automatically on startup