Didit MCP Server

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.

E-signature files

didit_session_get_signature_evidence, didit_session_get_signed_document and didit_session_get_signature_field_image return the same kind of link (plus content_type) for a signer's evidence PDF, the signed PDF of one document and the PNG of a signature field. They use the same MCP_PDF_DOWNLOAD_KEY and MCP_RESOURCE_URI; route /downloads/session-signature to this HTTP server as well. The file is checked against its recorded SHA-256 at issuance and again at download. didit_session_validate_signatures re-validates the signed documents and returns the result as JSON.

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.)

The one exception is the phone code pair, didit_verify_phone_send and didit_verify_phone_check: the console has no route for them, so the MCP reads the application's API key with your sign-in (a role with create:sessions and the didit:management scope, or an organization owner or admin for a local didit_account_login token) and calls the public phone API with it. The key is never returned, stored or logged.

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), Precise Location evidence (didit_session_get_location_evidence: every attempt and the same person's earlier checks behind a Location verdict).
• 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).
• Investigator (AI case reviewer): didit_investigator_queue_list, didit_investigator_report_get (recommendation, basis, evidence, precedents), didit_investigator_record_get (the review of one verification or transaction, open or decided), didit_investigator_add_note (a fact the user adds, as a team note the next review reads), questions, the free backtest (didit_investigator_backtest_start), performance, dashboard and Activity. Its decisions (didit_investigator_accept, _override, _batch_accept), policy answers (_question_answer, _question_dismiss) and the re-review that replaces the open report (_rereview, optionally with a note) are annotated destructive and refused without confirm: true, which a client sends only after the user approves that exact action. Every Investigator call sends X-Didit-Actor-Via: mcp (or copilot when the console assistant marks its request so), so the Investigator Activity shows where the user acted from.
• 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= 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:b5ff2371c2a41779d8421cf1333fd50706cb78f9eaa320656b0c30bdb7875226, 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.

| face_liveness_duplicated_face_name_mismatch_action | string