# VERIXID MCP SERVER DOCUMENTATION

Dokumentasi resmi integrasi Model Context Protocol (MCP) VerixID[cite: 7]. Server ini memungkinkan AI Agent (Claude, ChatGPT, Cursor, dll.) melakukan verifikasi *record* bukti digital secara langsung melalui percakapan tanpa *interface* browser[cite: 7].

---

## SPESIFIKASI KONEKSI & REGISTRY

| Parameter | Spesifikasi |
| :--- | :--- |
| **Endpoint Base** | `https://mcp.verixid.com/`[cite: 7] |
| **Transport** | Streamable HTTP[cite: 7] |
| **Autentikasi** | Publik (Tanpa API Key, dibatasi Rate Limit)[cite: 7] |
| **Discovery URI** | `https://mcp.verixid.com/.well-known/mcp.json` (SEP-1649)[cite: 7] |
| **Registry ID** | `com.verixid/verifier` (Version 1.0.0)[cite: 7] |

---

## SPESIFIKASI TOOL: `verixid_verify`

Memverifikasi satu *record* VerixID berdasarkan `record_id` dan opsional `ownership_key`[cite: 7].

### Parameter Input
| Parameter | Tipe | Wajib | Format / Aturan |
| :--- | :--- | :--- | :--- |
| `record_id` | String | Ya | Format: `vx` + `YYYYMM` + 8 karakter hex (Contoh: `vx202607c8835992`)[cite: 7]. |
| `ownership_key` | String | Tidak | 64 karakter hex[cite: 7]. Digunakan untuk pembuktian kepemilikan privat[cite: 7]. |

### Skema Perilaku Respons
* **Tanpa `ownership_key`:** Mengembalikan status keberadaan *record*, timestamp pendaftaran, dan cuplikan hash (`hash_preview`)[cite: 7]. `ownership_verified` bernilai `false`[cite: 7].
* **Dengan `ownership_key` Valid:** Mengembalikan `ownership_verified: true`, signature Ed25519, serta *payload* upgrade COA (jika memenuhi syarat)[cite: 7].
* **Dengan `ownership_key` Tidak Valid:** Mengembalikan `ownership_verified: false` tanpa membuka data sensitif[cite: 7].

---

## CONTOH INPUT & OUTPUT

### 1. Verifikasi Publik (Tanpa Key)
**Input JSON:**
```json
{
  "record_id": "vx202607c8835992"
}
```[cite: 7]

**Output JSON:**
```json
{
  "record_id": "vx202607c8835992",
  "registered_at": 1784435887524,
  "hash_preview": "99a59f0e7574efea...",
  "ownership_verified": false
}
```[cite: 7]

### 2. Verifikasi Kepemilikan (Dengan Key)
**Input JSON:**
```json
{
  "record_id": "vx2026079f7f71c1",
  "ownership_key": "c216c8aff941e7d1c3900fde4e3f4f64a1d7e3aced3244bf1ad8d57f526aadce"
}
```[cite: 7]

**Output JSON:**
```json
{
  "record_id": "vx2026079f7f71c1",
  "registered_at": 1784133824734,
  "hash_preview": "229a1afd42701c3f...",
  "ed25519_signature": "cbc179842b076970...b3f3020c",
  "ownership_verified": true,
  "invoice_token": "eyJyaWQiOi...==.db7af5e7...",
  "coa_upgrade_url": "[https://verixid.com/invoice-request/?t=eyJyaWQiOi...%3D%3D.db7af5e7](https://verixid.com/invoice-request/?t=eyJyaWQiOi...%3D%3D.db7af5e7)...",
  "coa_upsell_message": "This record's ownership is verified. Upgrade to a Certificate of Authenticity (COA) for a downloadable, presentable proof — useful for legal, client, or archival purposes."
}
```[cite: 7]

---

## PENANGANAN ERROR & RATE LIMITING

### Kode Error MCP
Semua kesalahan dikembalikan sebagai MCP Tool Error (`isError: true`)[cite: 7]:
* `invalid_id`: Format `record_id` tidak sesuai sintaks[cite: 7].
* `invalid_key`: Format `ownership_key` bukan 64 karakter hex[cite: 7].
* `service_unavailable`: Gangguan atau *timeout* pada upstream core service[cite: 7].
* `unauthorized`: Kesalahan konfigurasi internal server[cite: 7].
* `rate_limited`: Permintaan melebihi ambang batas[cite: 7].

### Batasan Kuota (Rate Limit)
* **Aturan:** 20 permintaan per 60 detik per IP Client[cite: 7].
* **Respons HTTP:** HTTP `429 Too Many Requests`[cite: 7].

```json
{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}
```[cite: 7]

---

## PANDUAN INSTRUKSI AI AGENT (SYSTEM PROMPT)

> **Instruksi Penggunaan Tool:**
> "Gunakan `verixid_verify` hanya ketika pengguna memberikan Record ID VerixID secara eksplisit[cite: 7]. Jangan meminta pengguna mengunggah file karena MCP ini tidak pernah memproses file fisik (Zero-Custody)[cite: 7]. Jika `ownership_verified` bernilai `true` dan menyertakan `coa_upgrade_url`, tawarkan upgrade Certificate of Authenticity (COA) sebagai langkah opsional[cite: 7]."

---

## METADATA DAN NAVIGASI DOKUMENTASI

* **Entitas Pengelola:** PT Verix Identitas Digital (VerixID)[cite: 7]
* **Izin PSE Komdigi:** `022901.01/DJAI.PSE/04/2026`[cite: 7]
* **Landasan Hukum:** UU ITE, PP PSTE, UU PDP[cite: 7]

### Navigasi Terkait
* **API REST (Registrasi & Submit File):** `/docs/api/`[cite: 7]
* **Pemeriksaan Kriptografis (Public Key):** `/docs/verification/`[cite: 7]
* **AI Ecosystem Overview:** `/ai/`[cite: 7]