Didit MCP Server

The official Model Context Protocol server for Didit — bring KYC, KYB, AML screening, transaction monitoring, biometrics, and full workspace operations to Claude, Cursor, VS Code, Windsurf, Zed, and any MCP client.

• 140+ tools across sessions, workflows, vendor users/businesses, transactions, networks, the standalone verification APIs, lists, cases, reports, webhooks, and billing.
• Auth is "Log in with Didit" (OAuth 2.1 + PKCE) — the MCP acts as the signed-in user with their role's permissions. There is no API-key mode: every tool calls the user-scoped console endpoints, which only accept a Bearer token.
• Tools call Didit REST endpoints. Session PDF generation returns a temporary download URL for the original PDF.

Full documentation: https://docs.didit.me/integration/mcp/overview

Session PDF downloads

didit_session_generate_pdf returns download_url, expires_at (UTC), and expires_in (300 seconds). Fetch the URL without an Authorization header to save the original Didit PDF. The server checks PDF access before issuing the link and fetches the original report again at download time using the same user and organization. It does not reconstruct the report from session data. If the session changes between issuance and download, the download reflects the current report. Revoked or expired user access can invalidate a link before its five-minute expiry.

Deployments must set MCP_PDF_DOWNLOAD_KEY to 32 cryptographically random bytes encoded as 64 hexadecimal characters, shared across all replicas, and set MCP_RESOURCE_URI to the public HTTPS MCP endpoint. Route /downloads/session-report.pdf to this HTTP server. The authenticated-encryption key protects the credentials embedded in the session-scoped link; rotating it invalidates outstanding links. Treat links as secrets and redact the token query parameter in proxy/access logs. Responses use Cache-Control: no-store.

Stdio deployments need a reachable HTTP deployment with the same key, API base URL, and MCP_RESOURCE_URI; stdio alone cannot serve download links. Missing key configuration produces an actionable tool error instead of inline PDF data.

Quick start

Hosted (recommended)

No install, no API key — point your client at the hosted URL and sign in via the browser:

https://mcp.didit.me/mcp

Claude Code

claude mcp add --transport http didit https://mcp.didit.me/mcp

Cursor (~/.cursor/mcp.json)

{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }

Windsurf / Zed (via the mcp-remote bridge)

{ "mcpServers": { "didit": { "command": "npx", "args": ["-y", "mcp-remote@latest", "https://mcp.didit.me/mcp"] } } }

See per-client setup for Claude Desktop and VS Code.

Authentication

The MCP is an OAuth 2.1 resource server; the Didit console (business.didit.me) is the authorization server. On first connect your client opens a browser, you Log in with Didit and approve the scopes, and the MCP then acts as you — across every organization you belong to, with your role's permissions. Tokens are short-lived and refreshed automatically.

Scopes: didit:management (workspace operations), didit:verification (running checks) and didit:staff (Didit staff accounts only; the authorization server never issues it to anyone else). Your console role is enforced server-side on every call.

There is no API-key mode. Every tool targets the user-scoped console endpoints (/organization/{org}/application/{app}/…), which authorize a Bearer token with per-role privileges and reject x-api-key. (For raw REST access with an application API key — e.g. creating sessions from your backend — use the REST API directly, not this server.)

See Authentication.

Tools

140+ tools, grouped by area. The full catalogue with read/write/destructive markers is in docs/TOOLS.md and at docs.didit.me. Highlights:

• Discovery & cross-app: didit_context_get, didit_session_search, didit_transaction_search, didit_vendor_user_search, didit_analytics — aggregate across every org/app in one call.
• Sessions: create, list, get decision, update status, reviews, bulk import, webhook delivery log + resend (didit_session_webhooks waits for a sandbox session's webhook so an integration can be verified end to end).
• Verification APIs: didit_verify_id, didit_verify_aml, didit_verify_face_match, didit_verify_kyb_search, …
• Workflows (incl. branching graphs): didit_workflow_search, didit_workflow_get_graph, didit_workflow_edit_graph — build conditional/branching workflows (fuzzy-match conditions, Document-AI steps) by sending small ops; large feature configs are kept server-side, never resent. didit_workflow_get_id_verification_methods_catalog and didit_workflow_get_kyb_registry_catalog answer the server-driven questions a config write depends on (which countries offer non-doc lookup / wallets, which KYB data tiers and monitoring a country's registries sell).
• Compliance: transaction monitoring, custom and preset rule management with backtesting, lists/blocklist/allowlist, cases, reports, audit logs, alerts.
• Workspace: questionnaires, webhooks, members, billing, branding.

File inputs

Tools that consume files (face upload, ID/PoA/liveness/face/age verification, branding) accept the file in one of two forms:

• *_path — an absolute path on the machine running the MCP server. Only works for local/stdio runs (e.g. Claude Code with a local server), where your files and the server share a filesystem.
• *_base64 — the file content inline, as raw base64 or a data: URL. Use this against the hosted endpoint; it is how the Didit Console Copilot passes chat attachments (its agent resolves attachment references like att_1 into base64 before the call reaches the MCP).

Both forms enforce the same 15MB cap and magic-bytes allow-list (png/jpg/jpeg/webp/gif/bmp/ico/pdf). The hosted transport's JSON body limit is 25MB (MCP_JSON_BODY_LIMIT).

Run it yourself

The hosted server above is the easy path — no install. To self-host, clone this repo and run it with Docker or Node. It authenticates the user the same way (OAuth, or a user Bearer token for headless runs); there is no API-key mode.

git clone https://github.com/didit-protocol/mcp.git && cd mcp

# Docker (recommended) — serves /mcp and /healthz on port 3000
docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp

# …or with Node
npm install && npm run build
node dist/http.js                                          # hosted HTTP/OAuth
DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js  # stdio (headless)

All Didit base URLs and OAuth endpoints are environment variables with public defaults (verification.didit.me, apx.didit.me, business.didit.me) — override them for a private deployment. See ARCHITECTURE.md and .env.example for the full reference.

Workflow feature configuration

Every workflow feature node takes a config object. The tables below are the complete contract - what didit_workflow_create, didit_workflow_update, didit_workflow_validate_graph, didit_workflow_set_graph and didit_workflow_edit_graph accept, and what the API stores. A key that is not listed here is not part of the contract and is dropped silently on save.

didit_workflow_get_feature_config_schema returns the same data as JSON at runtime.

Generated from schema/feature-config-schema.json (contract sha256:a2c413a50107faf3ea47fa187089a930ac17d3d04893e24176f494a58470e982, schema version 1), which is a copy of the artifact service-didit-verification generates from its feature-config serializers. Do not edit by hand — run npm run schema:readme.

AGE_ESTIMATION

Configuration for Age Estimation feature.

AML

Configuration for AML feature (used for both KYC AML and KYB Company AML).

BANK_VERIFICATION

Configuration for Bank Verification feature.

Bank Verification confirms who owns a bank account against an identity ANOTHER step established - it is not identity proof on its own. Put ID Verification, Database Validation or a questionnaire before it; first in a graph it has nothing to compare against and can only return unknown. The node is opt-in and runs nothing while bank_countries is empty.

DATABASE_VALIDATION

Configuration for Database Validation feature.

The node is opt-in and does nothing while database_validation_countries is empty - the editor blocks publishing in that state and the compliance check reports it as a gap. Place it after the step that produces its inputs (usually OCR), and use database_validation_field_sources only for inputs no upstream step can fill.

DOCUMENT_AI

Configuration for the Document AI feature.

At most 3 documents per node, field keys unique within a document, and at most one field per document may set is_full_name (it is optional - a document may mark none).

EMAIL_VERIFICATION

Configuration for Email Verification feature.

FACE_MATCH

Configuration for Face Match feature.

GEOLOCATION

Configuration for the Precise Location (GEOLOCATION) feature. Every threshold is bounded here rather than in the client: the browser and the native SDKs are told what to collect by the step data this config produces, and a value the server would refuse must never reach a user as a request their device cannot satisfy. The action keys all default to Review rather than Decline. A denied permission, a wide radius or a stale fix is not evidence of fraud, and a default that declined them would make the step a conversion trap.

IP_ANALYSIS

Configuration for Device & IP Analysis feature.

KYB_DOCUMENTS

KYB_KEY_PEOPLE

The workflow ids here point at separate KYC workflows: a KYB graph verifies the company, and the people behind it are verified by the linked person workflows.

KYB_REGISTRY

LIVENESS

Configuration for Liveness feature.

NFC

Configuration for NFC/ePassport feature.

OCR

Configuration for OCR/ID Verification feature.

Omitting documents_allowed stores the full country/document catalog, so the node accepts everything. Put OCR before any feature that reads identity data from the document (FACE_MATCH, NFC, DATABASE_VALIDATION).