Overview
Documint can run entirely on your own infrastructure. The documint-mcp package includes three entry points:
| Command | Purpose | Default port |
|---|---|---|
documint-server | REST API control plane | 8000 |
documint-mcp | MCP server for AI agents | stdio / 8100 |
documint | CLI 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
pip install documint-mcp
Requires Python 3.11 or later.
2. Start the API
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
curl http://127.0.0.1:8000/health
{
"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:
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):
{
"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)
| Variable | Default | Description |
|---|---|---|
HOST | 127.0.0.1 | Bind address |
PORT | 8000 | Bind port |
DEBUG | false | Enable debug mode (disables auth from localhost, enables Swagger UI at /docs) |
DATABASE_URL | sqlite:///./documint.db | Database connection string |
REDIS_URL | redis://localhost:6379/0 | Redis connection URL (optional in local mode) |
AUTH_TOKEN / DOCUMINT_AUTH_TOKEN | -- | Service bearer token for API access |
SECRET_KEY | random | Secret for session and token signing |
LOG_LEVEL | INFO | Structured logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL |
REPO_ROOT | auto-detected | Path to the repository root |
CACHE_TTL | 3600 | Default cache TTL in seconds (60-86400) |
MAX_FILE_SIZE | 10485760 | Maximum file size in bytes (10 MB) |
RATE_LIMIT_REQUESTS | 120 | Rate limit requests per minute |
Schema and bootstrap
| Variable | Default | Description |
|---|---|---|
DOCUMINT_AUTO_CREATE_SCHEMA | true (local) | Create database tables on startup |
DOCUMINT_AUTO_BOOTSTRAP_DEFAULTS | true (local) | Seed default workspace and project |
DOCUMINT_JOB_EXECUTION_MODE | inline (local) / queue (production) | inline runs jobs synchronously; queue uses arq workers |
DOCUMINT_ENVIRONMENT | auto-detected | local, test, or production environment name |
AI providers (for patch generation)
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | Anthropic API key for Claude-based patch drafting |
OPENROUTER_API_KEY | OpenRouter API key for fallback patch drafting |
HF_API_TOKEN | Hugging Face API token for summarization |
HF_PRIMARY_MODEL | Primary HF model for patch drafting |
HF_FAST_MODEL | Fast 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)
| Variable | Description |
|---|---|
GITHUB_APP_ID | GitHub App identifier |
GITHUB_APP_PRIVATE_KEY | PEM-encoded private key |
GITHUB_WEBHOOK_SECRET | Webhook signature secret |
GITHUB_API_URL | GitHub API base URL (default: https://api.github.com) |
Clerk authentication (optional)
| Variable | Description |
|---|---|
CLERK_JWKS_URL | Clerk JWKS endpoint for JWT verification |
CLERK_ISSUER | Expected JWT issuer |
CLERK_AUDIENCE | Expected JWT audience (optional) |
MCP server (documint-mcp)
| Variable | Default | Description |
|---|---|---|
DOCUMINT_API_KEY | -- | API key for the Documint REST API |
DOCUMINT_API_URL | https://api-production-285b.up.railway.app | Base URL of the Documint API |
DOCUMINT_MCP_TRANSPORT | stdio | Transport: stdio, sse, streamable-http |
DOCUMINT_MCP_HOST | 127.0.0.1 | Bind host for SSE/HTTP transports |
DOCUMINT_MCP_PORT | 8100 | Bind 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.
# Explicit
DATABASE_URL=sqlite:///./documint.db documint-server
PostgreSQL (production)
For production deployments, use PostgreSQL:
DATABASE_URL=postgresql://user:pass@localhost:5432/documint documint-server
Create the database first:
createdb documint
Important: In production (
DOCUMINT_ENVIRONMENTis notlocalortest), 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:
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:
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:
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=1andPYTHONDONTWRITEBYTECODE=1 - Uses the
scripts/entrypoint.shscript as the default command
For production deployments, ensure:
DEBUGisfalseDOCUMINT_AUTO_CREATE_SCHEMAisfalse(run migrations with alembic instead)DOCUMINT_AUTO_BOOTSTRAP_DEFAULTSisfalseDOCUMINT_JOB_EXECUTION_MODEisqueuewith 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:
# 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:
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:
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
pip install --upgrade documint-mcp
Database migrations are managed with alembic. After upgrading:
# For production (auto_create_schema disabled)
alembic upgrade head
# For local development (auto_create_schema enabled)
# Tables are created/updated automatically on startup