# Sealith MCP Quickstart

Base URL:

```text
https://www.sealith.com/api/mcp
```

Auth:

```text
OAuth 2.0 (recommended) or Authorization: Bearer sl_agent_...
```

Business plan or higher is required.

## Supported methods

- `initialize`
- `tools/list`
- `tools/call`

## Available tools

### 転送の作成・管理

- `create_secure_handoff` — ファイルまたはURLの handoff を作成します（`file` / `url` 両対応）
- `upload_handoff_chunk` — generic MCP クライアント向けの後方互換フローです。base64 chunk を追加します
- `complete_handoff_upload` — generic MCP クライアント向けの後方互換フローです。chunk upload を完了し、暗号化・確定処理へ進めます
- `cancel_handoff_upload` — 大容量ファイル転送の upload session を取り消します
- `get_handoff_status` — handoff のステータス・開封状況・ダウンロード数を取得します
- `finalize_handoff` — アップロード後に handoff を有効化し、受信者へ通知を送ります
- `revoke_handoff` — handoff を取り消します（未送信のパスコード通知も同時キャンセル）
- `list_handoffs` — キーワード・ステータス・宛先・日付でこのトークンの転送を検索します
- `bulk_revoke_handoffs` — 最大20件の handoff を一括取り消しします（監査ログに理由を記録可）

### 受信

- `receive_handoff` — 人が送った handoff を AI が受信します。file では暗号パラメータ、url では targetUrl を返します

### 監査・コンプライアンス

- `append_audit_context` — purpose / jobId / note / result を監査ログへ追記します
- `get_handoff_logs` — 個別 handoff の監査ログを取得します
- `get_org_usage` — プランの上限値と今月の転送利用状況（残件数・リセット日）を返します
- `verify_audit_integrity` — 組織の監査ログ全件の SHA-256 ハッシュチェーンを検証します

`create_secure_handoff` は `file` と `url` の両方に対応しています。`url` は Google Drive や Box などの共有URLを、パスコードと監査付きで渡す用途です。`file` は `textContent` を使う短いテキストメモだけ 1 回で完結します。PDF・画像・Office などのバイナリは、サイズに関係なく upload session を使います。

推奨フロー:
- Claude Code / Cursor のようなローカル実行型: `clientRuntime=local_helper + helperCommandExample`
- Claude App / ChatGPT のようなリモート実行型: URL共有と短い text file を先に検証し、binary file は client 側の shell / attachment / network 制約を確認する
- generic MCP クライアント: `clientRuntime=generic + upload_handoff_chunk`

## Initialize

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

## List tools

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

## Create handoff

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_secure_handoff",
    "arguments": {
      "purpose": "contract_review",
      "jobId": "job_123",
      "type": "file",
      "fileName": "nda.pdf",
      "fileSizeBytes": 524288,
      "mimeType": "application/pdf",
      "recipients": [{ "email": "legal@example.com" }],
      "message": "review only",
      "securityMode": "standard",
      "expiresInHours": 72,
      "maxDownloads": 3,
      "sensitivityLevel": "confidential"
    }
  }
}
```

## Create inline file handoff

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_secure_handoff",
    "arguments": {
      "purpose": "test_note_share",
      "jobId": "job_inline_001",
      "type": "file",
      "fileName": "test-note.txt",
      "fileSizeBytes": 28,
      "textContent": "Sealith MCP inline upload test",
      "recipients": [{ "email": "legal@example.com" }],
      "message": "review only",
      "securityMode": "standard",
      "expiresInHours": 72,
      "maxDownloads": 3,
      "sensitivityLevel": "confidential"
    }
  }
}
```

`textContent` を使うと、短いテキストファイルは暗号化・保管・確定・通知まで 1 回で完了します。Claude では PDF・画像・Office などのバイナリを `fileContentBase64` や `chunkBase64` で会話に載せないでください。会話上限に達しやすいため、バイナリはサイズに関係なく会話外アップロードへ寄せます。

## Remote client binary file note

1. `create_secure_handoff` を file で呼ぶ
2. `status: pending_upload` と `directUploadUrl` を受け取る
3. そのクライアントがローカル shell、添付ファイルのローカルパス、対象 host への network access を持つか確認する
4. 制約がある場合は、Claude Code / Cursor のようなローカル実行型か、自前の upload helper 経路へ切り替える

補足:

- このフローは「大きいファイル専用」ではなく、Claude や ChatGPT で扱う PDF / 画像 / Office / zip などのバイナリ全般に使います
- 理由は、base64 化したバイナリを会話に直接載せると、比較的小さい PDF でも会話上限に達しやすいためです
- generic MCP クライアント向けには `upload_handoff_chunk` / `complete_handoff_upload` も残していますが、会話欄に base64 を載せるクライアントでは優先しません

### リモートクライアント向け shell upload 例

```bash
curl -X POST \
  --data-binary @"/mnt/user-data/uploads/document.pdf" \
  -H "content-type: application/octet-stream" \
  "https://www.sealith.com/api/mcp-tools/upload-handoff-file?uploadSessionId=us_xxx&uploadToken=sut_xxx"
```

この shell upload は添付ファイルをそのまま送るため、会話欄に base64 を載せません。ただし、実際に使えるかはクライアントがローカル shell と対象 host への network access を許可しているかに依存します。

## Claude Code / Cursor / ローカル環境の helper 例

```bash
node scripts/sealith_upload_handoff_file.mjs \
  --upload-url "https://www.sealith.com/api/mcp-tools/upload-handoff-file?uploadSessionId=us_xxx&uploadToken=sut_xxx" \
  --file "/absolute/path/to/document.pdf"
```

この helper は repo にアクセスできるローカル環境向けです。Claude App や ChatGPT の remote connector では通常見えません。

## Create URL handoff

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "create_secure_handoff",
    "arguments": {
      "purpose": "dd_link_review",
      "jobId": "job_124",
      "type": "url",
      "url": "https://drive.google.com/file/d/xxx/view",
      "title": "DD資料共有リンク",
      "recipients": [{ "email": "legal@example.com" }],
      "message": "review only",
      "securityMode": "standard",
      "autoFinalize": true,
      "expiresInHours": 72,
      "maxDownloads": 3,
      "sensitivityLevel": "confidential"
    }
  }
}
```

## Receive handoff

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "receive_handoff",
    "arguments": {
      "transferId": "tr_xxxxxxxxxxxxxxxx",
      "passcode": "A2b!C3d@E4f#G5h$",
      "purpose": "contract_review",
      "recipientEmail": "legal@example.com"
    }
  }
}
```

`receive_handoff` は `file` の場合に暗号パラメータを返し、`url` の場合には `targetUrl`、`targetDomain`、`title` を返します。リンク先の閲覧権限は外部サービス側の設定に依存します。

## List handoffs (search)

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "list_handoffs",
    "arguments": {
      "status": "active",
      "q": "契約書",
      "limit": 20
    }
  }
}
```

`q` にはファイル名・タイトル・purpose・jobId・宛先メールアドレスが対象になります。`status`（draft / active / revoked / expired）、`recipientEmail`、`dateFrom` / `dateTo`（YYYY-MM-DD）でも絞り込めます。

## Bulk revoke handoffs

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "bulk_revoke_handoffs",
    "arguments": {
      "transferIds": ["tr_xxxxxxxxxxxxxxxx", "tr_yyyyyyyyyyyyyyyy"],
      "reason": "プロジェクト終了のため"
    }
  }
}
```

このトークンが作成した転送のみ取り消せます（最大20件）。`reason` は監査ログに記録されます。

## Get org usage

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_org_usage",
    "arguments": {}
  }
}
```

月間転送の残件数・プラン上限・ファイルサイズ上限などを返します。大量処理前のクォータ確認に使います。

## Verify audit integrity

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "verify_audit_integrity",
    "arguments": {}
  }
}
```

組織の監査ログ全件（最大1000件）の SHA-256 ハッシュチェーンを検証します。`ok: true` なら改ざんなし。コンプライアンス証跡・顧客向け監査報告に使います。

## Claude Code example

```bash
claude mcp add --transport http sealith https://www.sealith.com/api/mcp \
  --header "Authorization: Bearer ${SEALITH_AGENT_TOKEN}"
```

## Cursor example

```json
{
  "mcpServers": {
    "sealith": {
      "url": "https://www.sealith.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SEALITH_AGENT_TOKEN}"
      }
    }
  }
}
```

## Common JSON-RPC errors

- `invalid_request`
- `method_not_found`
- `tool_name_required`
- `tool_call_failed`
- `feature_not_available_on_plan`