> Need credentials? See: https://www.gocertius.io

Claude Desktop / Claude Code

Add to your ~/.claude.json or claudedesktopconfig.json:

{
  "mcpServers": {
    "gocertius": {
      "command": "npx",
      "args": ["-y", "@g-digital/mcp-gocertius"],
      "env": {
        "MCPAUTHUSER_KEY": "your-user-key",
        "MCPAPIBASE_URL": "https://api-gocertius.gocertius.io"
      }
    }
  }
}

Docker

docker run --rm -i 
  -e MCPAUTHUSER_KEY=your-user-key 
  -e MCPAPIBASE_URL=https://api-gocertius.gocertius.io 
  gdigital/gocertius:latest

Environment Variables

| Name | Required | Secret | Description |
| — | — | — | — |
| MCPALLOWINSECUREFILEURL | 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). |
| MCPALLOWUNVERIFIEDBEARER | No | No | Escape hatch for MCPHTTP_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. |
| MCPALLOWEDHOSTS | No | No | Comma-separated allowed Host headers. Empty = Host validation disabled (default). When set, requests with a Host outside the list are rejected. |
| MCPALLOWEDORIGINS | 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. |
| MCPAPIBASE_URL | Yes | No | Upstream API root. Required: your user key is exchanged for a session token against this host, and the server will not start without it. |
| MCPAUTHUSER_KEY | Yes | 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. (See https://www.gocertius.io for credential acquisition.) |
| MCPHTTPHOST | 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). |
| MCPHTTPMAXBODYBYTES | 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 MCPFILEMAX_BYTES applies. |
| MCPHTTPPUBLIC | No | No | Set to “true” for public/multi-tenant deployments. Activates Host validation and refuses to start unless (1) MCPALLOWEDORIGINS or MCPALLOWEDHOSTS is set AND (2) inbound Bearer introspection is configured (MCPSVCINTROSPECTURL + MCPSVCCLIENTID/SECRET) or MCPALLOWUNVERIFIED_BEARER=true is set explicitly (fail-closed). |
| MCPSVCCLIENTID | No | No | Client ID this server presents to the introspection endpoint above (its resource-server credentials). Only needed alongside MCPSVCINTROSPECTURL; it does not authenticate you to GoCertius. |
| MCPSVCCLIENTSECRET | No | Yes | Client secret this server presents to the introspection endpoint above (its resource-server credentials). Only needed alongside MCPSVCINTROSPECTURL; it does not authenticate you to GoCertius. (See https://www.gocertius.io for credential acquisition.) |
| MCPSVCINTROSPECTURL | No | No | RFC 7662 token introspection URL for inbound Bearer verification in HTTP mode. Opt-in, and required when MCPHTTP_PUBLIC=true. Leave empty for stdio (local) use. |
| PORT | No | No | HTTP port when running in hosted (HTTP) mode; ignored in stdio mode |

| Variable | Required | Description |
|—|—|—|
| MCPAUTHUSER_KEY | Required | Long-lived user key (exchanged for a session token) |
| MCPOTELENABLED | Optional | Set to true to enable OpenTelemetry tracing |
| MCPAPIBASE_URL | Required | Upstream API root. The user-key exchange authenticates against it, so the server does not start without it |

Bundled Skills

This package ships Claude Code slash-commands under .claude/commands/. After install, invoke them from Claude Code:

• /getting-started — step-by-step workflow guide
• /evidence-lifecycle — step-by-step workflow guide
• /dossier-lifecycle — step-by-step workflow guide
• /notification-lifecycle — step-by-step workflow guide
• /notification-attachments — step-by-step workflow guide
• /chat-lifecycle — step-by-step workflow guide

See docs/agent-prompts.md for end-to-end prompt examples and the tool sequences they trigger.

Prefer to code against the REST API directly?

You 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:

• Skill: .claude/skills/gocertius-suite-api/SKILL.md — open this repo in Claude Code and it is available directly.
• As a reference: docs/api-integration-skill.md.

It is independent of the MCP tools and the n8n node — pick whichever entry point fits your integration.

Available Tools

This server exposes 62 tools:

| Tool | Description |
|——|————-|
| evidencecreate | Registers a NEW evidence record inside an evidence group. Requires: evidencegroupcreate → evidenceGroupId, casefilecreate → 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 evidenceget/evidencelist, and ONLY THEN call evidenceseal. 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. |
| 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. |
| evidenceseal | 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 evidenceget/evidencelist. Requires casefilecreate → caseFileId and evidencegroupcreate → evidenceGroupId. Set evidencesCount to the number of evidences in the group. ASYNC: after calling, poll evidencegroup_list until the group status changes to CLOSED before linking to a dossier or generating certificates. |
| evidenceget | Retrieves a specific evidence record. Requires: evidencecreate → evidenceId, evidencegroupcreate → evidenceGroupId, casefilecreate → caseFileId. Returns status (COMPLETED|IN_PROCESS|ERROR), hash, and tspTimestamp when certified. |
| evidencegroupcreate | Creates an evidence group inside a case file. Requires: casefilecreate → 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. |
| evidencegrouplist | 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. |
| dossiercreate | Creates a dossier to aggregate certified evidence groups into a single tamper-evident PDF. Requires: casefilecreate → caseFileId. Evidence groups must be in CLOSED status before linking. Generate a UUID v4 string for id. Returns dossierId. After creation, link evidence with dossierevidencelink, then certify with dossiercertify. |
| dossierupdate | Updates the metadata of an existing dossier (name, template fields, expiry). Requires: dossiercreate → dossierId, caseFileId. Only available while dossier is in DRAFT status. |
| dossiercertify | Certifies a dossier, generating a tamper-evident PDF and locking all linked evidence. Requires: dossiercreate → dossierId, dossierevidencelink (evidence linked), casefilecreate → caseFileId. ASYNC: transitions DRAFT → CERTIFYING → CERTIFIED. Poll dossier_list until dossierId status === CERTIFIED before downloading. |
| 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. |
| dossierlistbyuser | Lists every dossier belonging to a user, across all of their case files. Requires: userId (from sessionlogin or sessioninfo). Use this when you do not know which case file a dossier is in; use dossierlist when you already have a caseFileId. Supports filter, order and page. Returns { data, meta.totalElements }. |
| 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. |
| dossiertemplatelist | Lists available dossier templates. No prerequisites. Returns template IDs and their translations per language. Use the returned id as dossierTemplateId in dossier_create. |
| dossier_preview | Returns an HTML preview URL of a dossier before certification. Requires: caseFileId and dossierId. |
| dossierdocumenturl | Returns the download URL for the certified dossier PDF. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId. |
| dossierpackageurl | Returns the download URL for the full dossier package (PDF + evidence files). Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId. |
| dossiervisibility | Updates the visibility (public/private) of a certified dossier. Requires: dossiercertify (CERTIFIED status), caseFileId, dossierId. |
| 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. |
| dossiergroupcertify | Creates AND certifies a dossier from a single sealed evidence group in one call (express path). Requires: evidenceseal (CLOSED status), casefilecreate → caseFileId, evidencegroup_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. |
| dossierevidencelink | Links evidence records from a sealed evidence group to a dossier. Requires: dossiercreate → dossierId, evidenceseal (CLOSED status), casefilecreate → 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. |
| dossierevidencelisttolink | Lists evidence items that are available to be linked to a dossier (CLOSED groups not yet linked). Requires: caseFileId and dossierId. |
| dossierevidencelist | Lists the evidence items linked to ONE evidence group of a dossier. Requires: caseFileId, dossierId AND dossierEvidenceGroupId — all three are mandatory. For every evidence item in the dossier regardless of group, use dossierevidencelistbydossier instead. Supports filter, order and page. |
| dossierevidencelistbydossier | Lists every evidence item linked to a dossier, across all of its evidence groups. Requires: caseFileId and dossierId. This is the dossier-wide view; dossierevidencelist is the narrower per-group one and additionally needs a dossierEvidenceGroupId. Supports filter, order and page. Returns { data, meta.totalElements }. |
| dossierevidenceget | Retrieves details of a specific evidence item linked to a dossier. Requires: caseFileId, dossierId, evidenceId. |
| dossierevidencedelete | Removes an evidence item from a dossier. Only available while dossier is in DRAFT status. Requires: caseFileId, dossierId, evidenceId. |
| notificationdocumentadd | Attaches a document to a notification. Two steps: this call registers the file and returns { url }, a presigned upload URL, and you then PUT the raw bytes to that URL with an x-amz-checksum-sha256 header. Generate a UUID v4 for id, and compute the file’s SHA-256 hex hash BEFORE calling — it goes in hash. ORDER MATTERS AND GETTING IT WRONG FAILS THE SEND: add every document BEFORE adding recipients, and wait until each document reaches READYTOSEND (poll notificationdocumentlist; roughly 8 seconds) before calling notificationrequestsend. Attaching after recipients, or sending while a document is still PENDING, returns 409/404 NOTIFICATIONNOTFOUND. The maximum number of attachments is a per-subscription setting rather than a fixed API limit, so do not assume a number. Attachments can be bundled into the delivery certificate — see notificationcertificatepackage_url. |
| notificationrequestcreate | Creates a certified notification request. Requires: casefilecreate → caseFileId. Generate a UUID v4 for id. Set language to enGB or esES. Returns notificationRequestId. Add at least one receiver with notificationreceiveradd 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 (