{ "markdown": "# GoCertius MCP Server\n\n[![npm version](https://img.shields.io/npm/v/@g-digital/mcp-gocertius)](https://www.npmjs.com/package/@g-digital/mcp-gocertius)\n[![npm downloads](https://img.shields.io/npm/dm/@g-digital/mcp-gocertius)](https://www.npmjs.com/package/@g-digital/mcp-gocertius)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![provenance](https://img.shields.io/badge/npm-provenance-green)](https://www.npmjs.com/package/@g-digital/mcp-gocertius)\n[![smithery badge](https://smithery.ai/badge/g-digital/gocertius)](https://smithery.ai/servers/g-digital/gocertius)\n\nMCP server for GoCertius: certified evidence, dossiers, notifications and chats via AI agents.\n\n## Quick start\n\n```bash\nnpx -y @g-digital/mcp-gocertius\n```\n\nOr see [ONBOARDING.md](ONBOARDING.md) for a step-by-step setup guide (≤ 5 minutes).\n\n## Where to install\n\nThis MCP is published to every major MCP distribution channel by the [g-digital MCP distribution pipeline](https://github.com/g-digital-by-Garrigues/MCP_Market_Distribution). Pick whichever fits your stack:\n\n| Channel | Install command / URL |\n|---|---|\n| **npm** | `npx -y @g-digital/mcp-gocertius` — [npmjs.com/package/@g-digital/mcp-gocertius](https://www.npmjs.com/package/@g-digital/mcp-gocertius) |\n| **Docker Hub** | `docker pull gdigital/gocertius:latest` — [hub.docker.com/r/gdigital/gocertius](https://hub.docker.com/r/gdigital/gocertius) |\n| **MCP Official Registry** | Auto-discovered as `io.github.g-digital-by-Garrigues/gocertius` — [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/v0/servers/io.github.g-digital-by-Garrigues/gocertius) |\n| **n8n community node** | Install `@g-digital/n8n-nodes-gocertius` in n8n Settings → Community Nodes — [npmjs.com/package/@g-digital/n8n-nodes-gocertius](https://www.npmjs.com/package/@g-digital/n8n-nodes-gocertius) |\n| **Smithery** | `smithery mcp install g-digital/gocertius` — [smithery.ai/servers/g-digital/gocertius](https://smithery.ai/servers/g-digital/gocertius) |\n\nEvery channel ships the same MCP server contract; the tools and environment configuration below apply regardless of which install path you choose.\n\n> Need credentials? Visit: [https://www.gocertius.io](https://www.gocertius.io)\n\n## Installation\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### Claude Code (CLI)\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### Cursor\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### Windsurf\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### Cline\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### VS Code\n\n```json\n{\n \"servers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### JetBrains\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### Zed\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"args\": [\n \"-y\",\n \"@g-digital/mcp-gocertius\"\n ],\n \"command\": \"npx\"\n }\n }\n}\n```\n\n> Need credentials? See: https://www.gocertius.io\n\n### Claude Desktop / Claude Code\n\nAdd to your `~/.claude.json` or `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"gocertius\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@g-digital/mcp-gocertius\"],\n \"env\": {\n \"MCP_AUTH_EMAIL\": \"your-email@example.com\",\n \"MCP_AUTH_PASSWORD\": \"your-password\"\n }\n }\n }\n}\n```\n\n### Docker\n\n```bash\ndocker run --rm -i \\\n -e MCP_AUTH_EMAIL=your-email@example.com \\\n -e MCP_AUTH_PASSWORD=your-password \\\n gdigital/gocertius:latest\n```\n\n## Environment Variables\n\n| Name | Required | Secret | Description |\n| --- | --- | --- | --- |\n| `MCP_ALLOW_INSECURE_FILE_URL` | No | No | Set to \"true\" to allow plain http:// fileUrl downloads in evidence_create (default https-only). Private/internal addresses are rejected regardless (resolution-time check; see the documented DNS TOCTOU limitation in the hosted-deployment runbook). |\n| `MCP_ALLOW_UNVERIFIED_BEARER` | No | No | Escape hatch for MCP_HTTP_PUBLIC=true WITHOUT inbound-token introspection: set to \"true\" ONLY when an upstream gateway already verifies Bearer tokens. The server logs a prominent warning and forwards tokens upstream unverified. |\n| `MCP_ALLOWED_HOSTS` | No | No | Comma-separated allowed Host headers. Empty = Host validation disabled (default). When set, requests with a Host outside the list are rejected. |\n| `MCP_ALLOWED_ORIGINS` | No | No | Comma-separated allowed browser Origins (DNS-rebinding defense). Empty = reject any request carrying an Origin header; non-browser clients (CLI/SDK) send no Origin and are always allowed. Use '*' to allow all. |\n| `MCP_API_BASE_URL` | No | No | Overrides the default upstream API host for every tool |\n| `MCP_AUTH_EMAIL` | No | No | Your GoCertius account email. Configure exactly one flow; do not combine it with the others. |\n| `MCP_AUTH_PASSWORD` | No | Yes | Your GoCertius account password. (See https://www.gocertius.io for credential acquisition.) |\n| `MCP_AUTH_USER_KEY` | No | Yes | Long-lived GoCertius user key, exchanged automatically for a short-lived session token. Use it for headless or automated access instead of an account password. Configure exactly one flow; do not combine it with the others. (See https://www.gocertius.io for credential acquisition.) |\n| `MCP_HTTP_HOST` | No | No | Interface the HTTP transport binds to. Default 127.0.0.1 (localhost only). Set 0.0.0.0 to expose on all interfaces (containers do this automatically). |\n| `MCP_HTTP_MAX_BODY_BYTES` | No | No | Maximum accepted POST /mcp request-body size in bytes (default 16777216 = 16 MiB — sized so base64 file uploads within the documented tool limits fit). Oversized requests get a 413 JSON-RPC error before/while reading — closes a memory-exhaustion DoS vector in public deployments. Note: base64 file sources are capped by this limit BEFORE MCP_FILE_MAX_BYTES applies. |\n| `MCP_HTTP_PUBLIC` | No | No | Set to \"true\" for public/multi-tenant deployments. Activates Host validation and refuses to start unless (1) MCP_ALLOWED_ORIGINS or MCP_ALLOWED_HOSTS is set AND (2) inbound Bearer introspection is configured (MCP_SVC_INTROSPECT_URL + MCP_SVC_CLIENT_ID/SECRET) or MCP_ALLOW_UNVERIFIED_BEARER=true is set explicitly (fail-closed). |\n| `MCP_SVC_CLIENT_ID` | No | No | Client ID this server presents to the introspection endpoint above (its resource-server credentials). Only needed alongside MCP_SVC_INTROSPECT_URL; it does not authenticate you to GoCertius. |\n| `MCP_SVC_CLIENT_SECRET` | No | Yes | Client secret this server presents to the introspection endpoint above (its resource-server credentials). Only needed alongside MCP_SVC_INTROSPECT_URL; it does not authenticate you to GoCertius. (See https://www.gocertius.io for credential acquisition.) |\n| `MCP_SVC_INTROSPECT_URL` | No | No | RFC 7662 token introspection URL for inbound Bearer verification in HTTP mode. Opt-in, and required when MCP_HTTP_PUBLIC=true. Leave empty for stdio (local) use. |\n| `PORT` | No | No | HTTP port when running in hosted (HTTP) mode; ignored in stdio mode |\n\n| Variable | Required | Description |\n|---|---|---|\n| `MCP_AUTH_EMAIL` | One of the two flows | Your account email |\n| `MCP_AUTH_PASSWORD` | One of the two flows | Your account password |\n| `MCP_AUTH_USER_KEY` | One of the two flows | Long-lived user key (exchanged for a session token) |\n| `MCP_AUTH_JWT` | Optional | Pre-seeded JWT (skips interactive login) |\n| `MCP_OTEL_ENABLED` | Optional | Set to `true` to enable OpenTelemetry tracing |\n| `MCP_API_BASE_URL` | Optional | Override upstream API base URL |\n\n## Bundled Skills\n\nThis package ships Claude Code slash-commands under `.claude/commands/`. After install, invoke them from Claude Code:\n\n- `/getting-started` — step-by-step workflow guide\n- `/evidence-lifecycle` — step-by-step workflow guide\n- `/dossier-lifecycle` — step-by-step workflow guide\n- `/notification-lifecycle` — step-by-step workflow guide\n- `/chat-lifecycle` — step-by-step workflow guide\n\nSee [docs/agent-prompts.md](docs/agent-prompts.md) for end-to-end prompt examples and the tool sequences they trigger.\n\n## Prefer to code against the REST API directly?\n\nYou don't have to go through this MCP server. This repo also ships a **Claude Code skill** — a standalone integration guide (authentication, call ordering, options, enums, gotchas) for programming directly against the REST API:\n\n- **Skill:** [`.claude/skills/gocertius-suite-api/SKILL.md`](.claude/skills/gocertius-suite-api/SKILL.md) — open this repo in Claude Code and it is available directly.\n- **As a reference:** [docs/api-integration-skill.md](docs/api-integration-skill.md).\n\nIt is independent of the MCP tools and the n8n node — pick whichever entry point fits your integration.\n\n## Available Tools\n\nThis server exposes **41 tools**:\n\n| Tool | Description |\n|------|-------------|\n| `evidence_create` | Registers a NEW evidence record inside an evidence group. Requires: evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Generate a UUID v4 for `id` and compute the SHA-256 hex hash BEFORE calling. INTERNAL flow: call with custodyType INTERNAL; the response returns uploadFileUrl (presigned S3 URL). PUT the exact file bytes to uploadFileUrl, then verify with evidence_get/evidence_list, and ONLY THEN call evidence_seal. Do not seal while any INTERNAL evidence file is not uploaded. EXTERNAL flow: use custodyType EXTERNAL only for intentional hash-only evidence; each evidence still needs a fresh UUID. If a previous evidence create/upload failed and outcome is unknown, verify with evidence_list before retrying and do not reuse the same id unless you confirmed it was not persisted. WARNING: the API sometimes returns {code:'EvidenceCreateError'} even when the evidence was successfully persisted. |\n| `evidence_list` | Lists all evidence records in a specific evidence group. Use to review uploaded documents before sealing the group, or to find a specific evidenceId. Requires: caseFileId and evidenceGroupId. Returns paginated list with IDs, titles, status, and timestamps. |\n| `evidence_seal` | Seals an evidence group and triggers qualified TSP timestamping. Requires: all INTERNAL evidence records in the group have already been uploaded to their uploadFileUrl and verified with evidence_get/evidence_list. Requires case_file_create → caseFileId and evidence_group_create → evidenceGroupId. Set evidencesCount to the number of evidences in the group. ASYNC: after calling, poll evidence_group_list until the group status changes to CLOSED before linking to a dossier or generating certificates. |\n| `evidence_get` | Retrieves a specific evidence record. Requires: evidence_create → evidenceId, evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Returns status (COMPLETED|IN_PROCESS|ERROR), hash, and tspTimestamp when certified. |\n| `evidence_group_create` | Creates an evidence group inside a case file. Requires: case_file_create → caseFileId. Generate a UUID v4 for `id`. Set evidenceType to FILE, PHOTO, VIDEO, or WEB_PLUGIN. Returns evidenceGroupId. One group can contain multiple evidence records. |\n| `evidence_group_list` | Lists all evidence groups in a case file with their current status (OPEN, CLOSING, CLOSED). Use to find an existing group or check which groups are ready for sealing. Requires: caseFileId. |\n| `dossier_create` | Creates a dossier to aggregate certified evidence groups into a single tamper-evident PDF. Requires: case_file_create → caseFileId. Evidence groups must be in CLOSED status before linking. Generate a UUID v4 string for `id`. Returns dossierId. After creation, link evidence with dossier_evidence_link, then certify with dossier_certify. |\n| `dossier_update` | Updates the metadata of an existing dossier (name, template fields, expiry). Requires: dossier_create → dossierId, caseFileId. Only available while dossier is in DRAFT status. |\n| `dossier_certify` | Certifies a dossier, generating a tamper-evident PDF and locking all linked evidence. Requires: dossier_create → dossierId, dossier_evidence_link (evidence linked), case_file_create → caseFileId. ASYNC: transitions DRAFT → CERTIFYING → CERTIFIED. Poll dossier_list until dossierId status === CERTIFIED before downloading. |\n| `dossier_list` | Lists all dossiers in a case file with their status and metadata. Use to find an existing dossierId or monitor certification progress. Requires: caseFileId. Returns paginated list with IDs, names, status, and creation dates. |\n| `dossier_get` | Retrieves the full details of a specific dossier including status, linked evidence, and download URLs. Use to check current state or get certificate download URLs after CERTIFIED. Requires: caseFileId and dossierId. |\n| `dossier_template_list` | Lists available dossier templates. No prerequisites. Returns template IDs and their translations per language. Use the returned id as dossierTemplateId in dossier_create. |\n| `dossier_preview` | Returns an HTML preview URL of a dossier before certification. Requires: caseFileId and dossierId. |\n| `dossier_document_url` | Returns the download URL for the certified dossier PDF. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId. |\n| `dossier_package_url` | Returns the download URL for the full dossier package (PDF + evidence files). Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId. |\n| `dossier_visibility` | Updates the visibility (public/private) of a certified dossier. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId. |\n| `dossier_delete` | Deletes a dossier. Available in DRAFT status (to discard before certification) or in CERTIFIED status (to permanently remove the certified dossier). Irreversible. Requires: caseFileId and dossierId. |\n| `dossier_group_certify` | Creates AND certifies a dossier from a single sealed evidence group in one call (express path). Requires: evidence_seal (CLOSED status), case_file_create → caseFileId, evidence_group_create → evidenceGroupId. Generate a UUID v4 string for `id`. Use when you have exactly one sealed evidence group and don't need multi-group aggregation. Returns dossierId immediately with CERTIFYING status → poll until CERTIFIED. |\n| `dossier_evidence_link` | Links evidence records from a sealed evidence group to a dossier. Requires: dossier_create → dossierId, evidence_seal (CLOSED status), case_file_create → caseFileId. Evidence groups MUST be in CLOSED status. Pass the ids array of evidence UUIDs to link. Can be called multiple times for evidence from different case files. |\n| `dossier_evidence_list_to_link` | Lists evidence items that are available to be linked to a dossier (CLOSED groups not yet linked). Requires: caseFileId and dossierId. |\n| `dossier_evidence_list` | Lists all evidence items linked to a dossier. Requires: caseFileId and dossierId. |\n| `dossier_evidence_get` | Retrieves details of a specific evidence item linked to a dossier. Requires: caseFileId, dossierId, evidenceId. |\n| `dossier_evidence_delete` | Removes an evidence item from a dossier. Only available while dossier is in DRAFT status. Requires: caseFileId, dossierId, evidenceId. |\n| `notification_document_add` | Performs the notification_document_add operation. Review the API documentation for full field details. |\n| `notification_request_create` | Creates a certified notification request. Requires: case_file_create → caseFileId. Generate a UUID v4 for `id`. Set language to en_GB or es_ES. Returns notificationRequestId. Add at least one receiver with notification_receiver_add before sending. IMPORTANT: The `content` field must be valid HTML — plain text without HTML tags will not render on the recipient landing page. Only the following HTML formats are supported: paragraphs (

), bold (), italic (), unordered lists (