Skip to main content
Glama

argus-face

Face Terminal is an HTTP API that checks a selfie shows the same person as an ID document or photo, and that the selfie is a genuine capture, not a printout, screen, mask or synthetic face. When the reference is a passport, ID card, residence permit or driving licence, the document is checked too. This repo holds the API spec, short client examples and a small MCP server. The face, spoof and document models are not in this repo.

Try it

export FACE_API_KEY=...   # your key

curl -s https://face.unbackoffice.com/v1/face/verify \
  -H "X-API-Key: $FACE_API_KEY" \
  -F reference=@id-photo.jpg \
  -F selfie=@selfie.jpg

Related MCP server: PaddleOCR-json MCP

Endpoints

Base URL https://face.unbackoffice.com. Send the key in the X-API-Key header.

Method

Path

Body (multipart/form-data)

POST

/v1/face/verify

reference (required: ID document page or clear face photo), selfie (required: taken now), back (back of an ID card or licence). JPEG, PNG or WebP, up to 12 MB each

POST

/v1/face/flash

Free, single-use flash challenge for a live capture clip recorded with liveness.js in your own page. See the docs

The full spec is in openapi.json.

Response

Trimmed. Real responses carry more detail per check.

{
  "result": {
    "status": "verified",
    "verified": true,
    "reasons": [],
    "match": {"assessment": "match", "similarity": 0.86, "confidence": 0.8, "discrepancies": []},
    "integrity": {"verdict": "authentic", "confidence": 0.8, "attack_signals": []},
    "liveness": null,
    "document": {"decision": "genuine", "document_type": "passport", "issuing_country": "CAN", "issues": []},
    "checked_at": "2026-10-11T09:30:00Z"
  }
}
  • status: verified (the faces match and the selfie looks genuine on every check that ran), review (something was inconclusive, reasons says what) or failed.

  • match.assessment: match, likely_match, inconclusive, likely_mismatch or mismatch.

  • integrity.verdict: authentic, review or suspect.

  • document.decision: genuine, review, suspect or none (the photo is not a document; a plain face photo is fine).

A result supports a human decision. It is not a certified biometric or liveness system. Review every review and failed result before you act on it.

Your data

Images are deleted within 24 hours of the check. The outcome (no images) is kept for 12 months. You need a lawful basis, usually the person's explicit consent, to send their face. See https://face.unbackoffice.com/terms and https://face.unbackoffice.com/privacy.

Limits

  • Your first key comes with free checks (the number is on https://face.unbackoffice.com/docs). One check is one call to /v1/face/verify. Flash challenges are free.

  • Invalid requests are not charged. A check that could not run (502/503) is given back.

  • Too many requests per minute for a key or an IP gets 429.

  • More checks: https://face.unbackoffice.com/tiers

Status

Meaning

400

A file is empty, or a clip was sent without consent

401

Missing, invalid or revoked key

402

No checks left on the key

403

The key can't call that endpoint

413

A file is too large

422

A required field is missing, e.g. no selfie

429

Too many requests. Wait and retry

502 / 503

The check could not run and was given back. Retry shortly

Examples

Both read FACE_API_KEY, send two images and print the outcome.

# Python 3.9+, needs requests
pip install requests
python examples/python/verify.py id-photo.jpg selfie.jpg

# TypeScript, Node 18+, no dependencies
npx tsx examples/typescript/verify.ts id-photo.jpg selfie.jpg

MCP server

A stdio MCP server that wraps the API, so an MCP client can run face checks. It runs straight from GitHub with npx, pinned to a release tag. Each call uses one check from your key.

Tool:

  • face_verify: reference and selfie (paths to image files on the machine the server runs on), optional back and full. Returns the status, reasons and the match, spoof and document checks, or the whole response with full: true.

Which files it reads:

  • face_verify uploads the files you name to Face Terminal. It reads a path only when it is a regular file that ends in .jpg, .jpeg, .png or .webp, holds JPEG, PNG or WebP content and is 12 MB or smaller. Links are resolved first and the file they point to must pass the same checks.

  • Set FACE_ALLOWED_DIR to a folder (several, separated like PATH) and nothing outside it is read. Add it to the env block below, for example "FACE_ALLOWED_DIR": "/Users/you/face-checks".

  • A path should come from you, not from a web page or a document your agent has read. A refused path gets one general message; the exact reason is in the server's log (stderr).

  • Text in a result is derived from the images. Treat it as data, not as instructions to your agent.

Claude Code

claude mcp add argus-face -e FACE_API_KEY=your-key -- npx -y "github:sect0rial/argus-face#v0.1.1"

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project) take the same block:

{
  "mcpServers": {
    "argus-face": {
      "command": "npx",
      "args": ["-y", "github:sect0rial/argus-face#v0.1.1"],
      "env": { "FACE_API_KEY": "your-key" }
    }
  }
}

Restart the client after editing the file.

Pin what you run. github:sect0rial/argus-face#v0.1.1 installs that release and nothing newer. Without the #… part npx runs whatever is on the default branch at that moment, with your API key in its environment. For the strictest pin, put the release's full commit SHA after the # instead of the tag (the SHAs are on the tags page): a tag can be moved, a commit cannot. Keep the github:sect0rial/ prefix: this repository is the only place the server is published.

mcp/dist is committed so npx needs no build step. CI rebuilds it from mcp/src on every push and pull request and fails if the committed files differ.

From a clone:

npm ci                 # installs the locked dependencies
npm run build          # compiles mcp/src to mcp/dist; commit the result with the source change
npm test               # checks the path and base URL guards against a local stub (no API call, no key)
npm run verify         # starts the server, runs initialize and tools/list, calls face_verify once

FACE_API_URL overrides the base URL (default https://face.unbackoffice.com). The images and your API key are sent to that host, so an override is refused unless it is https (plain http for localhost only) and FACE_ALLOW_CUSTOM_URL=1 is set too. Leave both unset unless you run your own test server, and check any MCP config you are given for them.

openapi.json

Saved from the live service and pretty-printed:

curl -s https://face.unbackoffice.com/openapi.json | python3 -m json.tool --indent 2 --no-ensure-ascii > openapi.json

Fetched on 14 November 2026, then edited: form fields that an API key cannot use are left out and the endpoint notes are rewritten. Make the same edits after a new fetch. For everything else the live document is the reference if the two differ.

What is not here

The face match, spoof and document models run on Face Terminal's servers. They are not in this repo and not under its licence.

Licence

The code in this repo is MIT licensed. See LICENSE.

Available Tools

1 tool
face_verifyCheck a selfie against an ID or photoA

Check that a selfie shows the same person as an ID document or face photo, and that the selfie is a genuine capture (not a printout, screen, mask or synthetic face), via Face Terminal (POST /v1/face/verify). When the reference is a passport, ID card, residence permit or driving licence, the document is checked too. Takes local file paths (JPEG, PNG or WebP, up to 12 MB each). Returns status (verified, review or failed), reasons, the face match, the spoof check and the document check. Uses one check from the key's quota. You need a lawful basis, usually the person's explicit consent, to send their face. A result supports a human decision.

Inputs: selfie (required), reference (required), back, full.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool, so there is no possibility of misselection between tools. Its purpose (1:1 face/document verification with liveness and spoof detection) is stated unambiguously in the description.

    Naming Consistency4/5

    The single name face_verify is snake_case and descriptive, so there is no inconsistency to speak of. It is noun-first rather than the common verb_noun convention, but with one tool no pattern is broken.

    Tool Count3/5

    The server wraps what appears to be a single Face Terminal verification endpoint, so one tool is defensible, but the surface is thin. There are no adjacent tools such as checking API/quota status or retrieving prior verification results, which would be reasonable companion operations.

    Completeness4/5

    The one tool covers the full verification lifecycle in a single call: status, reasons, face match, spoof check and document check, with clear input constraints (file paths, formats, size). Minor gaps remain, such as no way to query remaining quota or fetch historical/async results.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      fixRAgent, by AR Logic LLC, turns one photo of a building problem into what it is, how urgent it is (EMERGENCY, TODAY, THIS WEEK or WHENEVER), which trade to call, and what to tell the resident. For property managers, landlords and companies. NARPM member. Free Test Drive for up to 10 doors; paid plans from $39/mo. fixragent.com/pricing Remote MCP server: fixragent.com/mcp
      3
      MIT