@verifik/mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,66 +1,22 @@
 # @verifik/mcp
 
-Thin [Model Context Protocol](https://modelcontextprotocol.io) adapter for Verifik SmartCheck / Database Screening endpoints.
+Connect your AI assistant to **Verifik** — identity verification, document checks, vehicle lookups, business validation, and background screening across Latin America and worldwide. This package is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes the Verifik APIs your account already has access to as tools in Cursor, Claude Desktop, or any MCP client.
 
-Each MCP tool maps 1:1 to an `AppFeature` from `GET /v2/app-features/my-list`. Tool calls proxy to the existing Verifik REST API with your API token, so auth, ClientFeature gating, and credit deduction stay unchanged.
+Each paid tool call goes straight to the Verifik REST API with your API token. Credits are charged on your Verifik account the same way as a direct API call.
 
-## Architecture
+## Quick start
 
-```mermaid
-flowchart LR
-  A[MCP Client\nCursor / Claude Desktop] -->|stdio JSON-RPC| B["@verifik/mcp"]
-  B -->|GET /v2/app-features/my-list| C[Verifik API]
-  B -->|Bearer token proxy| C
-  C --> D[Existing middleware chain\nvalidateClient + billing]
-```
-
-Data flow:
-
-1. On boot, the server loads the client catalog from `GET /v2/app-features/my-list`.
-2. Eligible features become MCP tools (name derived from `code`, schema from `dependencies[]`).
-3. `tools/call` proxies to `${VERIFIK_API_BASE}/${feature.url}` using the feature `method`.
-4. Credits are charged by the normal API path — this server does not implement billing.
-
-## Requirements
-
-- Node.js 18+
-- A Verifik **API token** from the Smart-Agent **API Tokens** screen (`/settings/api-key`)
+1. **Get an API token** — sign in to [Smart-Agent](https://ai.verifik.co), open **Settings → API Tokens**, and create a token.
+2. **Add the MCP server** to your client (examples below).
+3. **Restart** your MCP client, then ask your assistant to verify an identity, run a background check, or look up a vehicle.
 
-API tokens are client JWTs minted by `POST /v2/auth/renew-and-revoke` while you are logged in. They include `clientId` and `JWTPhrase`, so they work for the catalog call and for feature endpoints the MCP proxies.
-
-## Install (recommended)
+No install step is required. MCP clients run the server with:
 
 ```bash
 npx -y @verifik/mcp
 ```
 
-No global install required. MCP clients invoke the package via `npx` (see configuration below).
-
-### Local development fallback
-
-```bash
-cd verifik-mcp
-npm install
-node server.js
-```
-
-## Environment variables
-
-| Variable | Required | Default | Description |
-| --- | --- | --- | --- |
-| `VERIFIK_API_TOKEN` | **Yes** | — | API token / client JWT from Smart-Agent |
-| `VERIFIK_API_BASE` | No | `https://api.verifik.co` | API base URL (use `https://staging-api.verifik.co` for staging) |
-| `VERIFIK_MCP_SMARTCHECK_ONLY` | No | `true` | Only expose `smartCheckEnabled` features |
-| `VERIFIK_MCP_COUNTRY` | No | — | Comma-separated country filter (e.g. `Colombia,world`) |
-| `VERIFIK_MCP_BASE_CATEGORY` | No | — | Comma-separated `baseCategory` filter |
-| `VERIFIK_MCP_CODES` | No | — | Comma-separated feature code allowlist |
-| `VERIFIK_MCP_CATALOG_REFRESH_MS` | No | `0` | Optional in-memory catalog refresh interval |
-
-Security: keep the token in environment variables only. The server never logs the full JWT.
-
-## Cursor configuration (`mcp.json`)
-
-Add to your Cursor MCP settings (global or project-level):
+### Cursor (`mcp.json`)
 
 ```json
 {
@@ -71,17 +27,16 @@ Add to your Cursor MCP settings (global or project-level):
       "env": {
         "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
         "VERIFIK_API_BASE": "https://api.verifik.co",
-        "VERIFIK_MCP_SMARTCHECK_ONLY": "true",
-        "VERIFIK_MCP_COUNTRY": "Colombia,world"
+        "VERIFIK_MCP_SMARTCHECK_ONLY": "true"
       }
     }
   }
 }
 ```
 
-## Claude Desktop configuration
+### Claude Desktop
 
-`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent Claude Desktop config file:
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent config file on your OS:
 
 ```json
 {
@@ -91,112 +46,410 @@ Add to your Cursor MCP settings (global or project-level):
       "args": ["-y", "@verifik/mcp"],
       "env": {
         "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
-        "VERIFIK_API_BASE": "https://api.verifik.co"
+        "VERIFIK_API_BASE": "https://api.verifik.co",
+        "VERIFIK_MCP_SMARTCHECK_ONLY": "true"
       }
     }
   }
 }
 ```
 
-## Generic MCP JSON (other clients)
+### CLI (stdio MCP server)
+
+```bash
+export VERIFIK_API_TOKEN="YOUR_API_TOKEN"
+export VERIFIK_API_BASE="https://api.verifik.co"
+export VERIFIK_MCP_SMARTCHECK_ONLY="true"
+npx -y @verifik/mcp
+```
+
+The server speaks MCP over stdio. Point any MCP-compatible client at the same `npx` command and environment variables.
+
+## How tools are discovered
+
+You do **not** need to upgrade this package when Verifik adds new API endpoints. The server builds its tool list from your live account catalog at startup.
+
+### 1. Catalog load (`lib/catalog.js`)
+
+On boot, the server calls `GET /v2/app-features/my-list` on `VERIFIK_API_BASE` (default `https://api.verifik.co`), paginating through all pages (500 features per page). It sends your `VERIFIK_API_TOKEN` as a `Bearer` token.
+
+Each item in the response is an **AppFeature** with fields such as `code`, `name`, `description`, `url`, `method`, `country`, `baseCategory`, `smartCheckEnabled`, `dependencies[]`, and pricing metadata.
+
+### 2. Filtering (`lib/filters.js`)
+
+Features are kept or dropped based on your environment:
+
+| Filter | Source | Default / behavior |
+| --- | --- | --- |
+| SmartCheck only | `VERIFIK_MCP_SMARTCHECK_ONLY` | `true` — only features with `smartCheckEnabled: true` |
+| Country | `VERIFIK_MCP_COUNTRY` | Optional comma-separated list (e.g. `Colombia,Mexico,world`) |
+| Category | `VERIFIK_MCP_BASE_CATEGORY` | Optional comma-separated `baseCategory` values |
+| Code allowlist | `VERIFIK_MCP_CODES` | Optional comma-separated feature `code` values |
+
+A feature must have both `code` and `url` to become a tool.
+
+### 3. Tool schema (`lib/tool-schema.js`)
+
+Each eligible feature becomes one MCP tool:
+
+- **Tool name** — sanitized from the feature `code` (letters, digits, `.`, `_`, `-`; max 128 characters).
+- **Description** — feature name, country, description, plus a note that the call charges Verifik credits.
+- **Input schema** — built from `dependencies[]`:
+  - `String` → JSON Schema `string`
+  - `Number` / `Integer` → `number`
+  - `Boolean` → `boolean`
+  - `enum`, `min`, `max`, `description`, and `required` are preserved when present.
+
+Features whose dependencies include **binary fields** (images, selfies, file uploads, multipart) are **skipped** for now — the MCP transport cannot safely carry those payloads yet. Scalar-only endpoints (identity lookups, plates, background checks, etc.) are exposed.
+
+### 4. Meta tools (`lib/meta-tools.js`) — free, no credits
+
+Two helper tools are always available and do **not** call paid endpoints:
+
+| Tool | Purpose |
+| --- | --- |
+| `verifik_list_catalog` | List features available in the in-memory catalog, with optional `country`, `baseCategory`, `code`, and `smartCheckOnly` filters |
+| `verifik_get_feature` | Return full metadata and the input JSON Schema for one feature by `code` |
+
+Use these to search what your account can access before spending credits.
+
+### 5. Tool calls (`lib/proxy.js`)
+
+When the assistant calls a feature tool, the server proxies an HTTP request to `${VERIFIK_API_BASE}/${feature.url}` using the feature's `method` (usually `GET`). Arguments become query parameters (GET) or a JSON body (POST/PUT). Your token is sent as `Authorization: Bearer …`.
+
+The catalog can optionally refresh in memory when `VERIFIK_MCP_CATALOG_REFRESH_MS` is set to a positive interval (milliseconds).
+
+**New Verifik endpoints appear automatically** the next time the catalog loads — no package update required.
+
+## Response format
+
+MCP tool results are JSON text. Paid feature calls are wrapped so your assistant always sees the HTTP status and the Verifik body together:
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 312,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC&documentNumber=1234567890"
+  },
+  "body": { }
+}
+```
+
+### Verifik success envelope (`body` on HTTP 2xx)
+
+Successful Verifik API responses use a consistent envelope:
+
+| Field | Description |
+| --- | --- |
+| `data` | Main result — identity fields, vehicle record, background-check payload, etc. |
+| `signature` | Certification block: `message` (e.g. `"Certified by Verifik.co"`) and `dateTime` |
+| `id` | Short reference id for the certified response |
+| `billing` | Optional — present on some endpoints when dynamic pricing applies (`dynamicQueryApplied`, `chargedCredits`, etc.) |
+
+The examples below show the **full MCP tool result** (wrapper + `body`). All names and document numbers are fictional.
+
+---
+
+### Example 1 — Colombian national ID (cédula)
+
+**Tool:** `colombia_api_identity_lookup` (or the sanitized name for `v2/co/cedula` in your catalog)
+
+**Arguments:**
 
 ```json
 {
-  "mcpServers": {
-    "verifik-smartcheck": {
-      "command": "npx",
-      "args": ["-y", "@verifik/mcp"],
-      "env": {
-        "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
-        "VERIFIK_API_BASE": "https://api.verifik.co",
-        "VERIFIK_MCP_SMARTCHECK_ONLY": "true"
-      }
-    }
+  "documentType": "CC",
+  "documentNumber": "1234567890"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 284,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC&documentNumber=1234567890"
+  },
+  "body": {
+    "data": {
+      "documentType": "CC",
+      "documentNumber": "1234567890",
+      "firstName": "María",
+      "lastName": "Gómez López",
+      "fullName": "María Gómez López"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "January 16, 2024 3:44 PM"
+    },
+    "id": "AB123"
   }
 }
 ```
 
-### Local repo fallback (no npm publish yet)
+---
+
+### Example 2 — Peruvian DNI
+
+**Tool:** feature for `v3/pe/cedula`
+
+**Arguments:**
 
 ```json
 {
-  "mcpServers": {
-    "verifik-smartcheck": {
-      "command": "node",
-      "args": ["/absolute/path/to/verifik-mcp/server.js"],
-      "env": {
-        "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
-        "VERIFIK_API_BASE": "https://api.verifik.co"
-      }
-    }
+  "documentType": "DNI",
+  "documentNumber": "87654321"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 410,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v3/pe/cedula?documentType=DNI&documentNumber=87654321"
+  },
+  "body": {
+    "data": {
+      "documentType": "DNI",
+      "documentNumber": "87654321",
+      "firstName": "Carlos",
+      "lastName": "Vega Mendoza",
+      "fullName": "Carlos Vega Mendoza",
+      "dateOfBirth": "19-12-1995",
+      "civilStatus": "SOLTERO",
+      "sex": "M",
+      "address": "Av. Ejemplo 100"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "April 16, 2025 2:43 PM"
+    },
+    "id": "FHBCC"
   }
 }
 ```
 
-Restart Cursor / Claude Desktop after editing MCP config.
+---
+
+### Example 3 — Mexico CURP
 
-## Tools
+**Tool:** feature for `v2/mx/curp`
 
-### Meta tools (no credit charge)
+**Arguments:**
 
-- `verifik_list_catalog` — filtered feature summaries from the in-memory catalog
-- `verifik_get_feature` — full metadata + dependency JSON schema for one `code`
+```json
+{
+  "documentType": "CURP",
+  "documentNumber": "GOML900101HDFRNS09"
+}
+```
 
-### Feature tools
+**MCP result (HTTP 200):**
 
-One tool per eligible `AppFeature`:
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 356,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/mx/curp?documentType=CURP&documentNumber=GOML900101HDFRNS09"
+  },
+  "body": {
+    "data": {
+      "documentType": "CURP",
+      "documentNumber": "GOML900101HDFRNS09",
+      "firstName": "Luis",
+      "lastName": "Ramírez",
+      "fullName": "Luis Ramírez",
+      "dateOfBirth": "1990-01-01",
+      "nationality": "Mexican"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "January 16, 2024 3:44 PM"
+    },
+    "id": "MX001"
+  }
+}
+```
 
-- **Name:** sanitized `code` (`A-Za-z0-9._-`, max 128 chars)
-- **Description:** name, country, description, credit note
-- **Input schema:** built from `dependencies[]`
-  - `String` → `string`
-  - `Number` / `Integer` → `number`
-  - `Boolean` → `boolean`
-  - `enum`, `min`, `max`, `description`, `required`
-- **Call behavior:** HTTP proxy to the feature `url` using `method` (`GET` query params by default)
+---
 
-Features with binary/file dependencies (images, selfies, uploads) are skipped until a safe transport exists.
+### Example 4 — Chile RUN / RUT
 
-## Smoke test
+**Tool:** feature for `v2/cl/cedula`
 
-### 1. Unit tests (no live token)
+**Arguments:**
 
-```bash
-cd verifik-mcp
-npm test
+```json
+{
+  "documentType": "RUN",
+  "documentNumber": "123456789"
+}
 ```
 
-### 2. Missing token exits cleanly
+**MCP result (HTTP 200):**
 
-```bash
-node server.js
-# stderr: VERIFIK_API_TOKEN is required (client JWT / API bearer token)
-# exit code: 1
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 298,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/cl/cedula?documentType=RUN&documentNumber=123456789"
+  },
+  "body": {
+    "data": {
+      "documentType": "RUN",
+      "documentNumber": "123456789",
+      "firstName": "Valentina",
+      "lastName": "Soto",
+      "fullName": "Valentina Soto"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "January 16, 2024 3:44 PM"
+    },
+    "id": "CL001"
+  }
+}
 ```
 
-### 3. Live catalog load (requires token)
+---
 
-```bash
-export VERIFIK_API_TOKEN="YOUR_API_TOKEN"
-node -e "
-  const { loadConfig } = require('./lib/config');
-  const { loadCatalogState } = require('./lib/catalog');
-  (async () => {
-    const config = loadConfig();
-    const state = await loadCatalogState(config);
-    console.log('tools:', state.tools.length);
-    console.log('sample:', state.tools.slice(0, 3).map(t => t.name));
-  })().catch(err => { console.error(err.message); process.exit(1); });
-"
+### Example 5 — Colombia vehicle by plate
+
+**Tool:** feature for `v2/co/runt/vehicle-by-plate`
+
+**Arguments:**
+
+```json
+{
+  "plate": "ABC123"
+}
 ```
 
-### 4. MCP stdio handshake
+**MCP result (HTTP 200):**
 
-Start the server via Cursor MCP panel, or use any MCP client that supports stdio transport.
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 520,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/runt/vehicle-by-plate?plate=ABC123"
+  },
+  "body": {
+    "data": {
+      "plate": "ABC123",
+      "brand": "Toyota",
+      "model": "Corolla",
+      "year": 2019,
+      "color": "Blanco",
+      "status": "Activo"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "March 10, 2025 11:20 AM"
+    },
+    "id": "RUNT01"
+  }
+}
+```
+
+---
+
+### Example 6 — Brazil background check (CPF)
+
+**Tool:** feature for `v2/br/background-check`
+
+**Arguments:**
+
+```json
+{
+  "documentType": "CPF",
+  "documentNumber": "123.456.789-00",
+  "dateOfBirth": "17/02/1990"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 1840,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/br/background-check?documentType=CPF&documentNumber=123.456.789-00&dateOfBirth=17%2F02%2F1990"
+  },
+  "body": {
+    "data": {
+      "documentType": "CPF",
+      "documentNumber": "123.456.789-00",
+      "firstName": "Ana",
+      "lastName": "Oliveira",
+      "fullName": "Ana Oliveira",
+      "dateOfBirth": "17/02/1990",
+      "status": "clear",
+      "canIssueReports": true
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "April 11, 2023 12:25 PM"
+    },
+    "id": "BR001"
+  }
+}
+```
+
+---
 
-## Example tool call result
+### Document / face / KYC endpoints
 
-Non-2xx responses are returned as MCP text with HTTP status and JSON body so agents can handle `404`, `409`, and `402` the same as REST:
+Verifik offers document validation, face comparison, liveness, and enrollment flows (e.g. `v2/face-recognition/*`, `v2/biometric-validations/*`, `v2/document-validations/*`). Those APIs often require **image or file uploads**. This MCP server currently exposes only features with scalar parameters — binary dependencies are filtered out at catalog load time. Use the [Verifik REST API](https://docs.verifik.co) or [SmartEnroll](https://docs.verifik.co) directly for full document and biometric workflows until file upload support is added here.
+
+---
+
+### Error responses
+
+Non-2xx responses are still returned as structured JSON (marked as MCP errors) so agents can handle them:
+
+**404 — record not found:**
+
+```json
+{
+  "httpStatus": 404,
+  "statusText": "Not Found",
+  "durationMs": 198,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC&documentNumber=9999999999"
+  },
+  "body": {
+    "code": "DOCUMENT_NOT_FOUND",
+    "message": "Document not found"
+  }
+}
+```
+
+**409 — validation / missing parameter:**
 
 ```json
 {
@@ -214,18 +467,78 @@ Non-2xx responses are returned as MCP text with HTTP status and JSON body so age
 }
 ```
 
-## Publishing
+## Country coverage
+
+The exact tools you see depend on **your Verifik plan and enabled features**. The table below lists countries and representative endpoint paths from the [Verifik API catalog](https://docs.verifik.co/reference/endpoint-doc-index/). Each paid call consumes credits on your account.
+
+| Country / region | Example capabilities | Example API paths |
+| --- | --- | --- |
+| **Argentina** | National ID, business, vehicle, criminal record | `v2/ar/cedula`, `v2/ar/company`, `v2/ar/vehicle` |
+| **Bolivia** | National ID, business, vehicle, SOAT | `v2/bo/cedula`, `v2/bo/company`, `v2/bo/vehicle` |
+| **Brazil** | National ID, CPF background check, business (CNPJ), vehicle | `v2/br/cedula`, `v2/br/background-check`, `v2/br/company` |
+| **Canada** | Business, provincial driver license & plates | `v2/ca/company`, `v2/ca/ontario/driver-license` |
+| **Chile** | National ID (RUN), taxpayer (RUT), vehicle, driver license | `v2/cl/cedula`, `v2/cl/taxpayer`, `v2/cl/vehicle` |
+| **Colombia** | National ID, foreigner ID, police/judicial checks, RUNT vehicles, business (RUES/DIAN) | `v2/co/cedula`, `v2/co/runt/vehicle-by-plate`, `v2/co/policia/consultar` |
+| **Costa Rica** | National ID, business, vehicle | `v2/cr/cedula`, `v2/cr/company`, `v2/cr/vehicle` |
+| **Dominican Republic** | National ID | `v2/do/cedula` |
+| **Ecuador** | National ID, vehicle & fines | `v2/ec/cedula`, `v2/ec/vehiculo/placa` |
+| **El Salvador** | National ID (DUI) | `v2/sv/dui` |
+| **Guatemala** | National ID | `v2/gt/cedula` |
+| **Honduras** | National ID | `v2/hn/cedula` |
+| **India** | Voter ID (EPIC) | `v2/in/epic` |
+| **Mexico** | CURP, INE validation, business, vehicle by plate | `v2/mx/curp`, `v2/mx/ine`, `v2/mx/vehiculo/placa` |
+| **Panama** | National ID, business | `v2/pa/cedula`, `v2/pa/company` |
+| **Paraguay** | National ID (CIC), business, vehicle | `v2/py/cic`, `v2/py/company`, `v2/py/vehicle` |
+| **Peru** | DNI (v3), foreigner ID, driver license, vehicle & SOAT | `v3/pe/cedula`, `v2/pe/vehiculo/placa`, `v2/pe/driver-license` |
+| **Spain** | National ID, business, vehicle | `v2/es/cedula`, `v2/es/company` |
+| **United States** | SSN verification, business, state driver licenses, vehicle/VIN | `v2/usa/ssn`, `v2/usa/company`, `v2/usa/vehicle` |
+| **Uruguay** | National ID | `v2/uy/cedula` |
+| **Venezuela** | National ID, foreigner ID | `v2/ve/cedula`, `v2/ve/foreigner-id` |
+| **Worldwide** | Sanctions & watchlists (DEA, FBI, Interpol, OFAC, UN, Europol), IP geolocation, phone lookup | `v2/dea`, `v2/ofac`, `v2/interpol`, `v2/look-ups/phone` |
+
+Run `verifik_list_catalog` in your MCP client to see the live list for your token. Filter by country with `VERIFIK_MCP_COUNTRY` or the `country` argument on the meta tool.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `VERIFIK_API_TOKEN` | **Yes** | — | API token from Smart-Agent → API Tokens |
+| `VERIFIK_API_BASE` | No | `https://api.verifik.co` | API base URL (use `https://staging-api.verifik.co` for staging) |
+| `VERIFIK_MCP_SMARTCHECK_ONLY` | No | `true` | When `true`, only expose SmartCheck-enabled features |
+| `VERIFIK_MCP_COUNTRY` | No | — | Comma-separated country filter (e.g. `Colombia,Mexico,world`) |
+| `VERIFIK_MCP_BASE_CATEGORY` | No | — | Comma-separated `baseCategory` filter |
+| `VERIFIK_MCP_CODES` | No | — | Comma-separated feature code allowlist |
+| `VERIFIK_MCP_CATALOG_REFRESH_MS` | No | `0` | In-memory catalog refresh interval in ms (`0` = load once at startup) |
+| `VERIFIK_MCP_REQUEST_TIMEOUT_MS` | No | `90000` | Per-call HTTP timeout in ms (some endpoints can take 40–60s; increase if you see timeout errors) |
+
+## Security
 
-Published as [`@verifik/mcp`](https://www.npmjs.com/package/@verifik/mcp) from this directory.
+- Your API token stays on **your machine** in environment variables (or your MCP client's secure config). The server never logs the full token.
+- Tool calls go **directly** from your machine to `api.verifik.co` (or your configured base URL). This package does not proxy through a third-party host.
+- Use a dedicated API token with the minimum access your workflow needs. Rotate tokens from the Smart-Agent dashboard if compromised.
+- Handle personal data according to your privacy policy and applicable regulations. Verifik responses contain sensitive identity information.
 
-Release tags use the `v*` prefix (for example `v0.1.0`). See the repository workflow `.github/workflows/publish.yml`.
+## Troubleshooting
 
-## Follow-ups
+| Symptom | What to check |
+| --- | --- |
+| Server exits immediately with `VERIFIK_API_TOKEN is required` | Set `VERIFIK_API_TOKEN` in your MCP config `env` block |
+| No tools / empty catalog | Confirm the token is valid, your account has SmartCheck features enabled, and `VERIFIK_MCP_SMARTCHECK_ONLY` / country filters are not too restrictive |
+| `401` / authentication errors | Regenerate the token in Smart-Agent → API Tokens |
+| `402` / insufficient credits | Top up credits in your Verifik dashboard |
+| `404` on a lookup | The document or record was not found — normal for invalid or non-existent identifiers |
+| `409` on a lookup | Missing or invalid parameters — call `verifik_get_feature` with the feature `code` to see required fields |
+| Expected tool missing | It may require file/image upload (not supported yet), may not be SmartCheck-enabled, or may not be on your plan — use `verifik_list_catalog` to inspect |
+| Stale tool list after Verifik adds endpoints | Restart the MCP server, or set `VERIFIK_MCP_CATALOG_REFRESH_MS` to refresh periodically |
 
-- Streamable HTTP MCP transport for hosted deployments
-- Biometric / multipart endpoints once file upload bridging is defined
+## Links
 
-## Related
+- [Verifik documentation](https://docs.verifik.co) — API reference, guides, and endpoint index
+- [Smart-Agent dashboard](https://ai.verifik.co) — API tokens, SmartCheck catalog, Check Lists
+- [Verifik website](https://verifik.co) — product overview and contact
+- [Model Context Protocol](https://modelcontextprotocol.io) — MCP specification
 
-- GitHub issue: https://github.com/Open-Verifik/verifik-backend/issues/370
-- Support ticket: #1313
+## Requirements
+
+- Node.js 18+
+- A Verifik account with API access and available credits