Build your first integration.

Local stdio / public npm package

Give your VS Code or Claude Desktop agent Scanverion tools. The public npm package runs locally over stdio and uploads approved inputs to the API; OCR is not local. Hosted HTTP MCP is a restricted API-key developer preview, not general availability or MCP OAuth. This guide covers local stdio setup.

1. Install the package

Use Node.js 22 or newer and npm. Install the public package into a dedicated installation directory and run the command there. npm installs the Scanverion SDK dependency. No repository access is required.

npm install @scanverion/mcp-server@0.1.1

2. Configure your client

Merge this into .vscode/mcp.json, or your user MCP configuration. VS Code prompts for the key in a masked input. Do not put the key in a chat.

No key is entered or stored on this page. An empty directory disables local file access; base64 still requires explicit upload approval.

{
  "inputs": [
    {
      "id": "scanverion-api-key",
      "type": "promptString",
      "description": "Scanverion API key",
      "password": true
    }
  ],
  "servers": {
    "scanverion": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/path/to/mcp/node_modules/@scanverion/mcp-server/dist/index.js"
      ],
      "env": {
        "SCANVERION_API_URL": "https://api.scanverion.com",
        "SCANVERION_ALLOWED_DIRECTORIES": "[]",
        "SCANVERION_TIMEOUT_MS": "120000",
        "SCANVERION_API_KEY": "${input:scanverion-api-key}"
      }
    }
  }
}

3. Verify without processing

With the key set in your terminal environment, run the doctor command. It checks directories and authenticated capabilities, but does not upload files or prove processing entitlement.

node ./node_modules/@scanverion/mcp-server/dist/index.js --doctor

In the MCP client, call list_capabilities and read scanverion://guide. That separate packaged guide is in English and includes MCP Inspector instructions and a synthetic-sample walkthrough.

Tools and billing

analyze_document

Billable. Detection by default; request Scanner explicitly for OCR and field extraction.

analyze_vehicle

Billable. Supports Detection and Blur.

list_capabilities

Unbilled AI model and limit catalog, not an entitlement check.

list_api_capabilities

Unbilled public API catalog, not account-specific access.

get_usage_summary

Unbilled calls and credits for inclusive YYYY-MM-DD dates. Estimated cost is unavailable, not zero.

First document call

Use a synthetic or approved sample in the allowed directory. This call uploads the file and may consume credits.

{
  "filePath": "C:/approved-samples/sample.png",
  "operations": [
    "Scanner"
  ],
  "scannerFields": [
    "documentNumber"
  ],
  "idempotencyKey": "sample-document-001"
}

Supply exactly one of filePath or imageBase64. Base64 needs a supported filename or MIME type. JPEG, PNG, WebP and PDF inputs must be non-empty and at most 10 MiB. Results retain JSON text and add structuredContent.data.

Troubleshooting and safe retries

• CONFIGURATION_ERROR: Check the key, absolute directory array, HTTPS API origin and timeout (1,000 to 300,000 ms).
• INVALID_INPUT: Check file access, format, base64, operations and date range.
• 401 / 403: Check key validity, workspace access and the process:write scope.
• 402 / 429: Check credits or rate limits. Inspect the error code, request ID and retryability.
• Timeouts and cancellation do not guarantee a refund or that backend work stopped. Automatic retries are disabled. Reuse the same idempotency key only for the same logical request; a duplicate can return 409.

Do not allow entire home directories. Resolved-path checks block traversal and symlink escapes but are not an OS sandbox. Do not expose this process to untrusted clients or allow other users to mutate its approved directories. Treat extracted document text as untrusted data, not instructions.