VeriLock MCP

@clevertech-os/verilock-mcp is a read-only Model Context Protocol server for VeriLock document metadata and cryptographic evidence. It connects to the existing https://verilock.online API and never accepts document bytes or returns signature image bytes.

Phase 1 tools

Every tool is annotated readOnlyHint: true, destructiveHint: false, idempotentHint: true, and openWorldHint: true. Signing and all mutations remain in the VeriLock application.

Related MCP server: proofrelay

Stdio setup

npm install
npm run build
VERILOCK_TOKEN=your-verilock-session-token npm start

Example client configuration after cloning and building this repository:

{
  "mcpServers": {
    "verilock": {
      "command": "node",
      "args": ["/absolute/path/to/verilock-mcp/dist/stdio.js"],
      "env": { "VERILOCK_TOKEN": "your-verilock-session-token" }
    }
  }
}

The package is prepared for a future npm release as @clevertech-os/verilock-mcp, but Phase 1 is currently distributed from this GitHub repository.

Streamable HTTP setup

npm run build
npm run start:http

The endpoint is POST /mcp; health is GET /healthz. The HTTP entry point forwards only the current request's Authorization: Bearer ... header. It does not use VERILOCK_TOKEN, which is reserved for stdio. Put the endpoint behind HTTPS and an access control layer before exposing it outside a trusted network.

Configuration

Copy .env.example to .env for local use. VERILOCK_API_BASE_URL defaults to https://verilock.online. HTTPS is mandatory except for http://localhost, http://127.0.0.1, and http://[::1]. The base URL is fixed at process startup and cannot be supplied by a tool caller. Request timeouts default to 10 seconds and response bodies default to a 1 MiB limit.

Privacy and security

The server forwards the session token only to the configured VeriLock API and never logs it. Upstream errors are sanitized before being returned to an MCP client. Auth-required calls fail locally when no token is present. Hash verification accepts only a 64-character hexadecimal SHA-256 digest. URL path parameters are encoded as one segment. Keep tokens in environment secrets, use TLS, and grant MCP clients only the access they need.

Deployment

The included Dockerfile runs the HTTP transport on port 8787 as the unprivileged node user. A typical deployment sets VERILOCK_API_BASE_URL, configures a TLS reverse proxy, and restricts /mcp to intended clients. Do not put a long-lived user token in a public URL or image layer.

The container sets VERILOCK_HTTP_HOST=0.0.0.0 so its published port is reachable. The non-container default remains 127.0.0.1 for safer local development.

Development

npm install
npm run format
npm run build
npm test
npm audit --omit=dev

See CONTRIBUTING.md and SECURITY.md.