Gocertius

GoCertius MCP Server

MCP server for GoCertius: certified evidence, dossiers, notifications and chats via AI agents.

Quick start

npx -y @g-digital/mcp-gocertius

Or see ONBOARDING.md for a step-by-step setup guide (≤ 5 minutes).

Where to install

This MCP is published to every major MCP distribution channel by the g-digital MCP distribution pipeline. Pick whichever fits your stack:

Channel	Install command / URL
npm	npx -y @g-digital/mcp-gocertius — npmjs.com/package/@g-digital/mcp-gocertius
Docker Hub	docker pull gdigital/gocertius:latest — hub.docker.com/r/gdigital/gocertius
MCP Official Registry	Auto-discovered as io.github.g-digital-by-Garrigues/gocertius — registry.modelcontextprotocol.io
n8n community node	Install @g-digital/n8n-nodes-gocertius in n8n Settings → Community Nodes — npmjs.com/package/@g-digital/n8n-nodes-gocertius
Smithery	smithery mcp install g-digital/gocertius — smithery.ai/servers/g-digital/gocertius

Every channel ships the same MCP server contract; the tools and environment configuration below apply regardless of which install path you choose.

Need credentials? Visit: https://www.gocertius.io

Installation

Claude Desktop

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

Claude Code (CLI)

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

Cursor

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

Windsurf

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

Cline

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

VS Code

{
  "servers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

JetBrains

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

Zed

{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx",
      "env": {
        "MCP_API_BASE_URL": "https://api-gocertius.gocertius.io",
        "MCP_AUTH_USER_KEY": "<PASTE_MCP_AUTH_USER_KEY_HERE>"
      }
    }
  }
}

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

Claude Desktop / Claude Code

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

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

Docker

docker run --rm -i \
  -e MCP_AUTH_USER_KEY=your-user-key \
  -e MCP_API_BASE_URL=https://api-gocertius.gocertius.io \
  gdigital/gocertius:latest

Environment Variables

Name	Required	Secret	Description
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).
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.
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.
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.
MCP_API_BASE_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.
MCP_AUTH_USER_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.)
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).
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.
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).
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.
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.)
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.
PORT	No	No	HTTP port when running in hosted (HTTP) mode; ignored in stdio mode

Variable	Required	Description
MCP_AUTH_USER_KEY	Required	Long-lived user key (exchanged for a session token)
MCP_OTEL_ENABLED	Optional	Set to true to enable OpenTelemetry tracing
MCP_API_BASE_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
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.
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.
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.
evidence_get	Retrieves a specific evidence record. Requires: evidence_create → evidenceId, evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Returns status (COMPLETED
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.
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.
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.
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.
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.
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.
dossier_list_by_user	Lists every dossier belonging to a user, across all of their case files. Requires: userId (from session_login or session_info). Use this when you do not know which case file a dossier is in; use dossier_list 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.
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.
dossier_preview	Returns an HTML preview URL of a dossier before certification. Requires: caseFileId and dossierId.
dossier_document_url	Returns the download URL for the certified dossier PDF. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.
dossier_package_url	Returns the download URL for the full dossier package (PDF + evidence files). Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.
dossier_visibility	Updates the visibility (public/private) of a certified dossier. Requires: dossier_certify (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.
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.
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.
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.
dossier_evidence_list	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 dossier_evidence_list_by_dossier instead. Supports filter, order and page.
dossier_evidence_list_by_dossier	Lists every evidence item linked to a dossier, across all of its evidence groups. Requires: caseFileId and dossierId. This is the dossier-wide view; dossier_evidence_list is the narrower per-group one and additionally needs a dossierEvidenceGroupId. Supports filter, order and page. Returns { data, meta.totalElements }.
dossier_evidence_get	Retrieves details of a specific evidence item linked to a dossier. Requires: caseFileId, dossierId, evidenceId.
dossier_evidence_delete	Removes an evidence item from a dossier. Only available while dossier is in DRAFT status. Requires: caseFileId, dossierId, evidenceId.
notification_document_add	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 READY_TO_SEND (poll notification_document_list; roughly 8 seconds) before calling notification_request_send. Attaching after recipients, or sending while a document is still PENDING, returns 409/404 NOTIFICATION_NOT_FOUND. 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 notification_certificate_package_url.
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 ( ), ordered lists ( ). Do not use other HTML tags or CSS. Avoid special typographic characters (em dashes, smart quotes) in subject; use standard ASCII equivalents (hyphen, straight quotes) instead.
notification_request_send	Sends the certified notification to all added receivers. Requires: notification_request_create → notificationRequestId, notification_receiver_add (at least one receiver), case_file_create → caseFileId. ASYNC: triggers delivery. Poll notification_request_status until status is SENT or beyond (PARTIALLY_READ, FULLY_READ) before generating certificates.
notification_request_status	Checks the delivery status of a certified notification. Requires: notificationRequestId, caseFileId. Returns status (CREATING
notification_receiver_add	Adds a recipient to a notification request. Requires: notification_request_create → notificationRequestId, case_file_create → caseFileId. The id can be a UUID v4 or custom string (e.g. your internal user ID). Returns receiverId — save it for notification_certificate_get. Delivery is by email always; set sendWaUrl for a WhatsApp link, sendSmsUrl for an RCS/SMS link (the channel negotiates: RCS where the handset supports it, SMS otherwise), and otpRequired to challenge the recipient with a one-time code. Any of those three needs phonePrefix (with the +) and phoneNumber. Add all receivers before calling notification_request_send — but if the notification has attachments, add those FIRST (see notification_document_add).
notification_certificate_get	Generates or retrieves a PDF certificate for a specific receiver proving delivery and/or reading of the notification. Requires: notification_request_send, notification_receiver_add → receiverId, notification_request_create → notificationRequestId, case_file_create → caseFileId. Generate a UUID v4 for id the first time you request a certificate for that receiver and reuse that same id when polling. Call only after notification_request_status is SENT or beyond. The first call may return {} while the certificate is being generated; poll/re-call notification_certificate_get until the response includes a pdfUrl/documentUrl or a CERTIFIED/final status. If the backend returns Forbidden/Unexpected at SENT, do not keep hammering the certificate endpoint: poll notification_request_status until READ/ANSWERED or verify in the UI, then retry with the same certificate id. For ACCEPTED_OR_NOT notifications, call once after a certifiable delivery/read state for an intermediate certificate and again after PARTIALLY_ANSWERED/FULLY_ANSWERED for the final answer certificate.
notification_request_list	Lists the certified notifications visible to a user. Requires userId (from session_login, session_info or profile_get) — this listing is user-scoped, not case-file-scoped, so it spans every case file unless you filter. Use this to recover a notificationRequestId you no longer have; it is the only way to find one. Returns per notification: id, code, subject, status, type, sentAt, receiverStats and the owning caseFile. Filter by status or statuses (CREATING, DRAFT, IN_PROCESS, SENT, PARTIALLY_READ, FULLY_READ, PARTIALLY_ANSWERED, FULLY_ANSWERED), by caseFileIds, by search over the subject, or by receiversSearch to find the notification sent to a given recipient. Paginated.
notification_request_update	Edits a notification that has not been sent: subject, content, type and language. Requires notificationRequestId and caseFileId. content must be valid HTML — plain text is accepted by the API but does NOT render on the recipient landing page. Supported tags only: , , , , ; no other tags and no CSS. Keep subject to plain ASCII (no em dashes, no smart quotes), 100 characters maximum. TESTED: once the notification has been sent the API rejects this with 403 Forbidden, so editing only works before the send. To change which case file it belongs to use notification_request_case_file_move — this tool does not move it.
notification_request_delete	Deletes a notification. Requires notificationRequestId and caseFileId. There is no undo. TESTED: once the notification has been sent the API rejects this with 403 Forbidden — a sent notification is delivery evidence and cannot be removed. If you only want it filed elsewhere, use notification_request_case_file_move instead.
notification_request_duplicate	Creates a new DRAFT notification from an existing one, copying its content, its recipients and its attachments. Works whatever state the original is in, so this is how you resend to the same people or reuse a sent notification as a template. Generate a UUID v4 for id and supply a new subject; pass caseFileId in the body to place the copy in a different case file, or omit it to keep it alongside the original. THE COPY IS BUILT ASYNCHRONOUSLY: it starts in CREATING with zero recipients and zero documents, and fills in afterwards, so reading it immediately shows an empty notification that is not empty. Poll notification_request_status until the status is DRAFT before inspecting or sending it. Because recipients ARE copied, review them with notification_receiver_list before calling notification_request_send — otherwise you will send to the original list again.
notification_request_case_file_move	Moves a notification to a different case file. Note the two caseFileId values: the one in the path is where the notification is NOW, and the one in the body is the destination. Notifications are grouped by case file, and this is the only way to change that grouping without duplicating.
notification_receiver_list	Lists a notification's recipients with their individual delivery state. Returns per recipient: id, firstName, lastName, email, phonePrefix/phoneNumber, status (INVALID, READY_TO_SEND, SENT, READ, ANSWERED, ERROR), statusUpdatedAt, answer once they respond, emailBounced, and validationError (TAKEN, IS_DEFINED, IS_INVALID) for a rejected address. Worth calling before notification_request_send to see whether any address came back INVALID, and after sending to see who read or answered. Also the way to recover a receiverId for notification_certificate_get. Paginated; filterable by id.
notification_receiver_update	Corrects a recipient's details: firstName, lastName, email, phonePrefix, phoneNumber. Requires receiverId, notificationRequestId and caseFileId. Use this to fix a mistyped address rather than deleting and re-adding, which would lose the receiverId. phonePrefix must include the + (for example +34). A phone number is required if the recipient is to receive the RCS/SMS link (sendSmsUrl), the WhatsApp link (sendWaUrl), or an OTP challenge (otpRequired).
notification_receiver_delete	Removes a recipient from a notification. Requires receiverId, notificationRequestId and caseFileId. To remove every address the platform rejected in one call, use notification_receiver_invalid_purge rather than deleting them one by one.
notification_receiver_add_bulk	Adds several recipients in one call instead of one notification_receiver_add per person. Pass receivers as an array; each entry needs id (you generate it), firstName, lastName and email, and may carry phonePrefix (with the +) and phoneNumber. Note this bulk form does NOT accept the per-recipient otpRequired, sendWaUrl or sendSmsUrl flags that the single-recipient tool does — set the defaults on the request instead (otpByDefault, sendWaUrlByDefault, sendSmsUrlByDefault). The maximum number of recipients is a per-subscription setting, not a fixed API limit: it varies by tenant and platform, so do not assume a number — add them and read the error if the tenant's cap is exceeded. Add every recipient before calling notification_request_send, then check the result with notification_receiver_list, since a rejected address appears with status INVALID.
notification_receiver_invalid_purge	Removes every recipient whose status is INVALID — addresses the platform rejected as malformed or duplicated — from a notification in a single call. Requires notificationRequestId and caseFileId. Recipients in any other status are left untouched. AN INVALID RECIPIENT BLOCKS THE SEND, so run this (or fix the addresses with notification_receiver_update) before notification_request_send, or the notification will not go out. Use notification_receiver_list first to see what will go.
notification_document_list	Lists the documents attached to a notification with their processing status, and it is what you poll after notification_document_add: a newly registered document starts at PENDING and reaches READY_TO_SEND in roughly 8 seconds. Calling notification_request_send while any document is still PENDING fails with 409/404 NOTIFICATION_NOT_FOUND. Poll with a bounded retry — every few seconds, a dozen attempts at most. Requires notificationRequestId and caseFileId. Paginated.
notification_document_delete	Removes an attachment from a notification. Requires documentId (from notification_document_list), notificationRequestId and caseFileId.
notification_document_download_url	Returns { downloadUrl }, a temporary link to an attachment as it was sent. Requires documentId (from notification_document_list), notificationRequestId and caseFileId. Use it to retrieve a file you attached or to verify what a recipient received. The URL is presigned and expires — fetch it when you need it rather than storing it.
notification_certificate_list	Lists the delivery certificates already generated for one recipient, so you can reuse one instead of generating a duplicate. Requires receiverId, notificationRequestId and caseFileId. Returns per certificate: id, status (DRAFT, CERTIFYING, CERTIFIED), language, createdAt, certifiedAt, partial — whether it is an intermediate certificate issued before the recipient finished responding — and embeddedDocuments. Do not read embeddedDocuments as "the package contains the attachments": in a tested run it was false on a notification that had an attachment, and notification_certificate_package_url still returned a ZIP carrying that attachment. Once a certificate is CERTIFIED, download it with notification_certificate_document_url (the certificate alone) or notification_certificate_package_url (a ZIP that also carries the attachments).
notification_certificate_document_url	Returns { documentUrl } for the certificate PDF on its own, WITHOUT the attachments. Requires certificateId, receiverId, notificationRequestId and caseFileId. Wait until the certificate is CERTIFIED: generation is asynchronous and the first call can 404 or come back empty while it is still CERTIFYING, so poll a few times with a bounded retry rather than hammering it. If you want the attachments bundled in, use notification_certificate_package_url instead.
notification_certificate_package_url	Returns { packageUrl } for a ZIP containing the certificate AND the notification's attachments — the "with annexes" form. There is no separate preview flag anywhere in the API: the package carries the annexes, the document is the certificate alone. Requires certificateId, receiverId, notificationRequestId and caseFileId. Same preconditions as notification_certificate_document_url — wait for CERTIFIED, and expect the first call to fail while generation is still running.
case_file_create	Creates a new case file — the top-level container for all related operations (evidence, notifications, dossiers, chats). Call this first before any other operation. Generate a UUID v4 for id. Returns caseFileId needed for all subsequent calls.
case_file_list	Lists all case files in your GoCertius account. Pass userId (from session_login or session_info) to scope results to your account. Returns paginated list with IDs, names, and status.
case_file_get	Retrieves details of a specific case file. Requires: caseFileId. Use to verify a case file exists before creating evidence groups, dossiers, or notifications.
case_file_delete	Deletes a case file and everything filed inside it — evidence groups, dossiers, notifications and their certificates. Irreversible, with no confirmation step and no recycle bin. Requires: caseFileId. Returns no body (HTTP 204); confirm with case_file_list. Do not call it to 'clean up' unless the user asked for that case file to be destroyed.
chat_create	Creates a certified chat channel (Telegram). IMPORTANT: Chats can only be created in the user's personal case file (created automatically when the GoCertius account was opened). Do not use a manually created case file — use session_info → case_file_list to find the personal case file (oldest createdAt, owned by the user). Generate a UUID v4 for id. Set service to Telegram. Returns immediately and the chat may start in status creating; call chat_get and wait until it is registered/active before requesting the invitation URL or certificates.
chat_get	Retrieves details of a certified chat. Requires: personal caseFileId and chat_create → chatId. Returns status, participants, and registeredAt timestamp. After chat_create, poll chat_get until status is active/registered and registeredAt is present; createdAt is not enough for certificate creation.
chat_invitation_url	Returns the Telegram invitation URL for a certified chat. Requires: chat_create → chatId and the personal caseFileId. Do not call while chat_get still shows status creating; wait until the chat is registered/active, otherwise the API can answer Chat not found. Share the returned invitationUrl with participants so they can join the certified channel.
chat_certificate_create	Creates a certificate of a range of messages from a certified chat. Requires: chat_create → chatId, personal caseFileId, chat_get → registeredAt, and messages already present in the Telegram channel. Generate a UUID v4 for id. Do not use createdAt as a substitute for registeredAt; if registeredAt is missing, the chat is not ready to certify. Specify chatMessagesFrom and chatMessagesTo as ISO timestamps (chatMessagesFrom must be AFTER registeredAt). ASYNC: poll chat_certificate_get until status === CERTIFIED.
chat_certificate_get	Retrieves the certificate of a certified chat. Requires: chat_certificate_create → certificate id, chat_create → chatId, case_file_create → caseFileId. Returns documentUrl when status reaches CERTIFIED. Poll until CERTIFIED before using documentUrl.
session_login	Forces the MCP server to re-authenticate with GoCertius. Takes NO parameters and accepts no credentials — the server re-exchanges the user key it was configured with (MCP_AUTH_USER_KEY) for a fresh session token and reports the resulting userId and expiry. The MCP server manages authentication automatically; call this only if you hit 401 errors. When the server holds no credential of its own (none configured, or you supplied your own Bearer token) there is no session of ours to renew and the tool returns an error naming MCP_AUTH_USER_KEY.
session_info	Retrieves information about the current authenticated session: userId, type (how this MCP session authenticated — always UserKey, the server's only auth flow), accountLoginType (a different fact: how the GoCertius account itself signs in, Password or OpenId, null if the API omits it), email, companyId and defaultCaseFileId. Use to verify who is authenticated or check session validity; identity is resolved via GET /profile. If you only need the userId, prefer profile_get — it is the canonical source (id) and returns the rest of the profile too. No required parameters.
profile_get	Returns the authenticated user's own profile. It identifies the caller from the session token alone — no email or any other input needed — so it works on every deployment, including a per-request Bearer one. Its id field IS your userId (UUID): the value required by case_file_list and every /users/{userId}/... operation. Prefer this over session_info when you need the userId: it is the canonical source. Also returns companyId (needed to subscribe to the notifications SSE stream) and defaultCaseFileId (the personal case file — the one chats must use). Also returns permit, a set of booleans — { evidences, idVerifications, notifications, chats, signatures } — that says which tool families this account may use at all: a false entry means every tool in that family returns 403 regardless of inputs, and no retry or different argument will help. Read it before calling into a family for the first time. Note that a family with no tools in this server will read false and that is expected, not a misconfiguration. No parameters.
evidence_upload	Uploads a local file as evidence in one step: computes its SHA-256, registers the evidence record (custodyType INTERNAL = GoCertius stores the file), and uploads the bytes to S3 — no manual hashing or PUT needed. Internally this follows the required GoCertius sequence: create INTERNAL evidence → receive uploadFileUrl (presigned S3 URL) → PUT file bytes → return uploaded:true. Requires: case_file_create → caseFileId, evidence_group_create → evidenceGroupId. Provide EXACTLY ONE of filePath (absolute local path, stdio/local mode only) or contentBase64 (base64-encoded file content, ~10 MB max). Use evidence_upload when the file is on the local machine; use evidence_create when you already have the SHA-256 hash, need to inspect/use uploadFileUrl manually, or have a public fileUrl. After this tool succeeds, verify with evidence_get/evidence_list and only then call evidence_seal. If this tool fails before returning an evidence id, check evidence_list before retrying; if retrying manually, use evidence_create with a fresh UUID. Local files must be under 1 GiB.
notification_send	Sends a certified notification to one or more recipients in a single call: creates the notification request, adds every recipient, and sends it. Generates every UUID itself — do not pass any id. Requires case_file_create → caseFileId. content MUST be HTML: plain text is accepted by the API and reports SENT but does not render on the recipient's landing page. Supported tags only: , , , , — no other tags, no CSS. Keep subject to plain ASCII, 100 characters maximum. Delivery is always by email; per recipient you can additionally set sendWaUrl (WhatsApp), sendSmsUrl (RCS or SMS depending on the handset) and otpRequired (one-time code), each of which needs phonePrefix with the + and phoneNumber. The maximum number of recipients is a per-subscription setting, not a fixed limit, so none is enforced here — the API rejects an oversized batch. This tool does NOT attach files; use notification_send_with_attachments for that, because attachments must be registered before recipients are added. PARTIAL SUCCESS IS REPORTED, NOT THROWN: if the request was created but a recipient or the send failed, the result still carries notificationRequestId together with recipientsAdded, recipientsFailed and sent:false, so you can finish with notification_receiver_add and notification_request_send instead of abandoning a draft. An INVALID recipient blocks the send, so this tool checks for one before sending and reports invalidRecipients rather than attempting a send that cannot succeed. If the initial create fails the tool raises an error instead: common causes are a caseFileId that does not exist, a subject over 100 characters, and an exhausted contracted notification plan, which no retry will fix. If that error is a timeout rather than a rejection, check notification_request_list before retrying — the request may have been created anyway. Poll notification_request_status for delivery progress, then notification_certificate_get per recipient.
notification_send_with_attachments	Sends a certified notification WITH one or more attached documents to one or more recipients, in a single call. Use notification_send instead when there are no attachments. This tool exists separately because attachments impose an ordering rule the API enforces and does not forgive: documents must be registered and fully uploaded BEFORE any recipient is added, and every document must reach READY_TO_SEND before the notification is sent — otherwise the send fails with 409/404 NOTIFICATION_NOT_FOUND. The tool performs that whole sequence for you: create → register and upload each document → wait for READY_TO_SEND → add recipients → send. Each attachment takes a local file path, base64 content, an HTTPS URL, or an n8n binary reference; the hash and the upload are handled internally. Generates every UUID itself — do not pass any id. Requires case_file_create → caseFileId. content MUST be HTML: plain text is accepted by the API and reports SENT but does not render on the recipient's landing page. Supported tags only: , , , , . Keep subject to plain ASCII, 100 characters maximum. Delivery is always by email; per recipient you can additionally set sendWaUrl (WhatsApp), sendSmsUrl (RCS or SMS depending on the handset) and otpRequired (one-time code), each of which needs phonePrefix with the + and phoneNumber. The maximum number of attachments and of recipients are per-subscription settings, not fixed limits, so neither is enforced here. IF AN ATTACHMENT FAILS THE RUN STOPS BEFORE RECIPIENTS ARE ADDED, on purpose: once recipients exist the API will not accept further documents, so continuing would produce a notification that can never carry the missing file. The result reports the draft's notificationRequestId so you can retry or delete it. An INVALID recipient blocks the send, so the tool checks for one before sending and reports invalidRecipients instead of attempting a doomed send. If the initial create fails the tool raises an error instead: common causes are a caseFileId that does not exist, a subject over 100 characters, and an exhausted contracted notification plan, which no retry will fix. If that error is a timeout rather than a rejection, check notification_request_list before retrying — the request may have been created anyway. Certificates can bundle the attachments — see notification_certificate_package_url.

Coexistence

This MCP server is the current, actively maintained interface for the GoCertius API.

It coexists safely with any other MCP servers in your setup — it exposes only GoCertius-namespaced tools and shares no local state with other servers.

License

MIT — see LICENSE.