Impri MCP Server

Impri — Approval Inbox for AI Agents

The imprimatur for your AI agents. Watchers watch the world, the Approval Inbox holds the agent's hands until a human says yes.

Quickstart

Docker Compose (< 5 minutes)

git clone https://gitlab.com/sekera.radim/impri.git
cd impri
docker compose up

Open http://localhost:8080 in your browser.

On first start the server prints the bootstrap Admin API key to the logs:

╔══════════════════════════════════════════════════════╗
║            IMPRI — FIRST RUN BOOTSTRAP               ║
╠══════════════════════════════════════════════════════╣
║  Admin API Key: im_...                               ║
║  Project ID:    proj_...                             ║
║  Store this key securely — it will not be shown again.║
╚══════════════════════════════════════════════════════╝

Copy the key, paste it into the login screen, and you're in.

Dev mode (hot-reload)

Terminal 1 — server:

cd server
npm install
npm run dev
# Server starts on http://localhost:8484

Terminal 2 — UI:

cd ui
npm install
npm run dev
# UI starts on http://localhost:5173
# /v1 requests are proxied to localhost:8484

API at a glance

Base URL: http://localhost:8484/v1
Auth: Authorization: Bearer im_<key>

Push an action (curl example)

curl -X POST http://localhost:8484/v1/actions \
  -H "Authorization: Bearer im_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "reddit.comment",
    "title": "Reply to: Why is resume advice so conflicting?",
    "preview": {
      "format": "markdown",
      "body": "The advice conflicts because..."
    },
    "target_url": "https://reddit.com/r/jobs/comments/...",
    "expires_in": 86400,
    "editable": ["preview.body"]
  }'

MCP server (Claude Code / agents)

npx @impri/mcp
# env: IMPRI_API_KEY=im_...  IMPRI_BASE_URL=http://localhost:8484

Project structure

server/   TypeScript + Fastify + SQLite — REST API (port 8484)
mcp/      MCP server (stdio) — thin wrapper over the REST API
ui/       Vue 3 + Vuetify — web inbox (port 5173 dev / 8080 Docker)
docker/   Dockerfiles (server.Dockerfile)
docs/     Research, ADRs

CLI

The impri CLI lets humans manage the inbox from a terminal — approve, reject, tail pending actions, add watchers, and manage keys — without writing any code.

# Build and install (local, pre-npm)
cd sdk/typescript && npm install && npm run build
cd ../cli && npm install && npm run build
npm install -g ./cli

# Connect to your instance
impri init --cloud --signup   # or: impri init (self-hosted)

# Common commands
impri inbox                   # pending actions
impri tail                    # live-tail new actions
impri approve act_abc123
impri watch add github-releases --param owner=fastify --param repo=fastify

• CLI reference

SDKs & integrations

v0.1, pre-release. Self-host is the complete path; the hosted cloud is early beta.

pip install -e sdk/python          # Python SDK (local, pre-PyPI)
npm install ./sdk/typescript       # TS SDK (local, pre-npm)
npx @impri/mcp                     # MCP server (published)

• Python SDK reference
• TypeScript SDK reference
• Integrations — LangChain, OpenAI Agents, CrewAI, n8n, Make, Zapier, webhook receivers
• Cookbook — recipes for email approval, SQL gating, social posts, idempotent batches, webhook verification, key rotation

Documentation

• Web docs: https://impri.dev/docs
• CLI reference — install, impri init, every command with examples, config + env precedence
• Quickstart — signup → first approved action in < 5 min
• Example agent — a complete, dependency-free agent that proposes an action, waits for approval, then acts and reports back
• How to add human approval to an AI agent
• Self-hosting — Docker, env vars, backups, reverse proxy
• Webhooks — HMAC verification, retries, polling fallback
• Inbox UX & Bulk API — keyboard shortcuts, bulk approve/reject, search/filter parameters, POST /v1/actions/bulk-decision reference
• Watcher presets — 18 ready-to-use templates (HN, Reddit, GitHub, npm, arXiv, …); REST + SDK + MCP usage
• Notification channels — Slack, Discord, Telegram, ntfy, email, and generic webhook; digest window, auto-disable, SSRF protection
• Telegram Approval Bot — in-chat Approve / Reject buttons; setup, security model, troubleshooting
• Audit log — event types, query API (GET /v1/audit), export (NDJSON/CSV), retention, and security model
• llms.txt — machine-readable index for AI assistants

Hosted cloud (beta): a managed instance runs at app.impri.dev / api.impri.dev. Self-serve signup is open: create a project + admin key with the Create an API key button at app.impri.dev, or POST /v1/signup. It's early beta, so self-host is still the most complete path.

Self-hosting notes

• SQLite data is persisted in a Docker volume (impri-data).
• Set WEBHOOK_SECRET env var to a random string for HMAC webhook signing.
• BASE_URL should match the public URL of your deployment (used in inbox_url links).

License

MIT — see LICENSE. Self-host the full core freely; the hosted cloud and team features are the paid offering (see MONETIZATION.md).