GoCertius_MCP

# GoCertius MCP Server

[![npm version](https://img.shields.io/npm/v/@g-digital/mcp-gocertius)](https://www.npmjs.com/package/@g-digital/mcp-gocertius)
[![npm downloads](https://img.shields.io/npm/dm/@g-digital/mcp-gocertius)](https://www.npmjs.com/package/@g-digital/mcp-gocertius)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![provenance](https://img.shields.io/badge/npm-provenance-green)](https://www.npmjs.com/package/@g-digital/mcp-gocertius)
[![smithery badge](https://smithery.ai/badge/g-digital/gocertius)](https://smithery.ai/servers/g-digital/gocertius)

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

## Quick start

```bash
npx -y @g-digital/mcp-gocertius
```

Or see [ONBOARDING.md](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](https://github.com/g-digital-by-Garrigues/MCP_Market_Distribution). Pick whichever fits your stack:

| Channel | Install command / URL |
|---|---|
| **npm** | `npx -y @g-digital/mcp-gocertius` — [npmjs.com/package/@g-digital/mcp-gocertius](https://www.npmjs.com/package/@g-digital/mcp-gocertius) |
| **Docker Hub** | `docker pull gdigital/gocertius:latest` — [hub.docker.com/r/gdigital/gocertius](https://hub.docker.com/r/gdigital/gocertius) |
| **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) |
| **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) |
| **Smithery** | `smithery mcp install g-digital/gocertius` — [smithery.ai/servers/g-digital/gocertius](https://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](https://www.gocertius.io)

## Installation

### Claude Desktop

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### Claude Code (CLI)

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### Cursor

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### Windsurf

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### Cline

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### VS Code

```json
{
  "servers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### JetBrains

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### Zed

```json
{
  "mcpServers": {
    "gocertius": {
      "args": [
        "-y",
        "@g-digital/mcp-gocertius"
      ],
      "command": "npx"
    }
  }
}
```

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

### Claude Desktop / Claude Code

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

```json
{
  "mcpServers": {
    "gocertius": {
      "command": "npx",
      "args": ["-y", "@g-digital/mcp-gocertius"],
      "env": {
        "MCP_AUTH_EMAIL": "your-email@example.com",
        "MCP_AUTH_PASSWORD": "your-password"
      }
    }
  }
}
```

### Docker

```bash
docker run --rm -i \
  -e MCP_AUTH_EMAIL=your-email@example.com \
  -e MCP_AUTH_PASSWORD=your-password \
  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 always rejected regardless. |
| `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_AUTH_EMAIL` | No | No | Your GoCertius account email (Flow 1). Configure one of Flow 1 or Flow 2. |
| `MCP_AUTH_PASSWORD` | No | Yes | Your GoCertius account password (Flow 1, email/password accounts) (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_PUBLIC` | No | No | Set to "true" for public/multi-tenant deployments. Activates Host validation and refuses to start unless MCP_ALLOWED_ORIGINS or MCP_ALLOWED_HOSTS is set (fail-closed). |
| `MCP_OPENID_CLIENT_ID` | No | No | OpenID Connect client ID (Flow 2) |
| `MCP_OPENID_ISSUER` | No | No | OpenID Connect issuer URL (Flow 2) |
| `MCP_OPENID_REFRESH_TOKEN` | No | Yes | OpenID Connect refresh token (Flow 2) (See https://www.gocertius.io for credential acquisition.) |
| `PORT` | No | No | HTTP port when running in hosted (HTTP) mode; ignored in stdio mode |

| Variable | Required | Description |
|---|---|---|
| `MCP_AUTH_EMAIL` | One of flow 1 or 2 | Your account email |
| `MCP_AUTH_PASSWORD` | One of flow 1 or 2 | Your account password |
| `MCP_OPENID_ISSUER` | One of flow 1 or 2 | OpenID Connect issuer URL |
| `MCP_OPENID_CLIENT_ID` | One of flow 1 or 2 | OpenID Connect client ID |
| `MCP_OPENID_REFRESH_TOKEN` | One of flow 1 or 2 | OpenID Connect refresh token |
| `MCP_AUTH_JWT` | Optional | Pre-seeded JWT (skips interactive login) |
| `MCP_OTEL_ENABLED` | Optional | Set to `true` to enable OpenTelemetry tracing |
| `MCP_API_BASE_URL` | Optional | Override upstream API base URL |

## 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
- `/chat-lifecycle` — step-by-step workflow guide

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

## Available Tools

This server exposes **40 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|IN_PROCESS|ERROR), hash, and tspTimestamp when certified. |
| `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