signdocs

SignDocs Brasil — MCP サーバー

Model Context Protocol に対応した、SignDocs Brasil 電子署名 API 用のサーバーです。MCP 対応の AI クライアント（Claude Desktop、Claude Code、Cursor、…）を使って、署名セッションの作成、複数署名者のエンベロープ管理、ドキュメントのアップロード／ダウンロード、署名の検証、Webhook の管理を行えます。公式の n8n、Zapier、Make.com の統合と同じアクションカタログを提供します。

OAuth2 トークンの交換、キャッシュ、リトライ、エラー処理を担う公式の @signdocs-brasil/api SDK の薄いアダプターです。

インストール

npm install -g @signdocs-brasil/mcp-server   # or run on demand with npx

認証情報

SignDocs ダッシュボード（app.signdocs.com.br → API）で API 認証情報を作成し、環境変数として設定してください。

変数	必須	デフォルト	備考
SIGNDOCS_CLIENT_ID	はい	—	OAuth2 クライアント ID
SIGNDOCS_CLIENT_SECRET	はい	—	OAuth2 クライアントシークレット
SIGNDOCS_ENVIRONMENT	いいえ	hml	hml（ステージング）または production
SIGNDOCS_BASE_URL	いいえ	自動設定	解決されたベース URL を上書きします
SIGNDOCS_SCOPES	いいえ	全スコープ	スペース区切りのスコープ上書き値

まずは hml で始めてください。HML のデータは約 7 日後に期限切れとなり、安全にテストできます。 実際に法的拘束力のある署名を作成する場合に限り、production に切り替えてください。

AI クライアントを接続する

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "signdocs": {
      "command": "npx",
      "args": ["-y", "@signdocs-brasil/mcp-server"],
      "env": {
        "SIGNDOCS_CLIENT_ID": "your_client_id",
        "SIGNDOCS_CLIENT_SECRET": "your_client_secret",
        "SIGNDOCS_ENVIRONMENT": "hml"
      }
    }
  }
}

Claude Code：

claude mcp add signdocs \
  -e SIGNDOCS_CLIENT_ID=your_client_id \
  -e SIGNDOCS_CLIENT_SECRET=your_client_secret \
  -e SIGNDOCS_ENVIRONMENT=hml \
  -- npx -y @signdocs-brasil/mcp-server

ツール

ツール	アクション	安全性
create_signing_session	単一署名者のセッションを作成し、signingUrl を返します	⚠️ 法的拘束力あり＋クォータ
get_signing_session_status	セッションのステータスをポーリングします	読み取り
get_signing_session	セッションの全情報を取得します	読み取り
list_signing_sessions	ステータスで一覧表示します	読み取り
cancel_signing_session	セッションをキャンセルします	⚠️ 取り消し不可
resend_signing_session_otp	OTP を再送します	書き込み
create_envelope	複数署名者のエンベロープを作成します	⚠️ 法的拘束力あり＋クォータ
get_envelope	エンベロープの詳細を取得します	読み取り
add_session_to_envelope	署名者を追加し、signingUrl を返します	⚠️ 法的拘束力あり＋クォータ
get_envelope_combined_stamp	署名が結合された PDF の URL を取得します	読み取り
upload_document	トランザクションに PDF を添付します	書き込み
download_document	署名付きダウンロード URL を取得します	読み取り
list_transactions	トランザクションを検索／一覧表示します	読み取り
get_transaction	トランザクションの詳細を取得します	読み取り
cancel_transaction	トランザクションをキャンセルします	⚠️ 取り消し不可
get_evidence	暗号学的証拠を取得します	読み取り
verify_evidence	公開証拠を検証します	読み取り
verify_envelope	公開エンベロープを検証します	読み取り
verify_document	PDF 内の署名を検出します	⚠️ PROD 専用＋クォータ
register_webhook / list_webhooks / delete_webhook / test_webhook	Webhook を管理します	混在

⚠️ ツールには destructiveHint アノテーションと説明内の警告が付いているため、準拠クライアントは実行前にユーザーへ確認を求めます。 アノテーションはあくまでヒントです。クライアントの自動承認設定を確認してください。

まだ公開されていない機能

Trust セッション（/v1/trust-sessions）と resend-invite は、まだ @signdocs-brasil/api v1.6.1 に含まれていません。SDK が対応した時点で追加されます。 デジタル ICP-Brasil A1 署名は、ホスト型セッションのプロファイルではなく、より低レベルのトランザクション／advance フローを通じて実行します。

リソース

サーバーは、モデルが必要に応じて読み取れる、コンテキスト補完用のリソースを公開します。

• signdocs://quickstart — 最小限の署名フローと安全性に関する注意事項
• signdocs://policy-profiles — 有効な policyProfile の値と CUSTOM ステップ
• signdocs://webhook-events — 購読可能なすべてのイベントタイプ

リモート HTTP トランスポート（マルチテナント）

同じツールはStreamable HTTP経由でも提供されるため、1つのデプロイで多くの AI エージェント／テナントに対応できます。それぞれが独自の SignDocs 認証情報を使ってセッションごとに認証します（サーバーに共有シークレットを埋め込む必要はありません）。

npm run start:http        # or: signdocs-mcp-http   (listens on PORT, default 3000)
# or containerized:
docker build -t signdocs-mcp . && docker run -p 3000:3000 signdocs-mcp

エンドポイント： POST /mcp（Streamable HTTP）。MCP の initialize リクエストでは、Authorization ヘッダーによる認証が必要です。

• Authorization: Bearer <token> — SignDocs OAuth2 アクセストークン（/oauth2/token から取得）を API にそのまま渡します。
• Authorization: Basic base64(clientId:clientSecret) — サーバーが client_credentials のトークン交換を代行します。
• X-SignDocs-Client-Id + X-SignDocs-Client-Secret — 2つのプレーンなヘッダーで同じクライアント認証情報を指定します（Base64 なし）。値を変換できないヘッダーのみのクライアント向けです。

X-SignDocs-Environment: hml|production でセッションごとに環境を選択します（デフォルトはサーバーに設定された環境です）。

サーバーは OAuth 2.0 リソースサーバーとして動作します。SignDocs 認可サーバーを指す GET /.well-known/oauth-protected-resource（RFC 9728）を提供し、認証されていない initialize に対して 401 と WWW-Authenticate を返します。トークンの検証は、引き続き SignDocs API が正式に行います。GET /healthz は認証不要のヘルスプローブです。

Bearer を使うクライアント設定の例：

{
  "mcpServers": {
    "signdocs-remote": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": {
        "Authorization": "Bearer <signdocs_access_token>",
        "X-SignDocs-Environment": "hml"
      }
    }
  }
}

サーバーの環境変数： PORT、HOST、SIGNDOCS_ENVIRONMENT（デフォルト環境）、MCP_PUBLIC_URL（プロキシの背後でリソースメタデータを提供する場合）、MCP_CORS_ORIGIN、MCP_DNS_REBINDING_PROTECTION=true + MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS（本番環境では推奨）。

セッションはプロセス内メモリに保持されるため、単一インスタンスで実行するか、スティッキーなルーティングを使用してください。マルチインスタンス／サーバーレスの場合は、スティッキーセッションを利用するか、セッションマップを共有ストア + EventStore（再開機能）に置き換えてください。既存の external-api Lambda + API Gateway に NestedStack としてデプロイするのが、本番環境で想定される方法です。

AWS Lambda

サーバーレスホスティングでは、@signdocs-brasil/mcp-server/lambda が createLambdaHandler をエクスポートします。これは MCP トランスポートをステートレスに実行する API Gateway HTTP API v2 ハンドラーです（呼び出しごとにサーバーを1つ起動し、セッションストアは使いません）。Bearer／Basic 認証にも対応しています。SignDocs はこれを mcp-hml.signdocs.com.br / mcp.signdocs.com.br でホストしています。

import { createLambdaHandler } from '@signdocs-brasil/mcp-server/lambda';
export const handler = createLambdaHandler({ defaultEnvironment: 'hml' });

開発

npm install
npm run build      # tsc → dist/
npm test           # vitest (pure unit tests, no network)
npm run inspect    # build + launch MCP Inspector against the stdio server

ロードマップ

• v0.1： ローカル stdio サーバー、完全なツールカタログ、環境認証情報。
• v0.2（今回のリリース）： セッションごと、テナントごとの認証（Bearer のパススルーまたは Basic によるクライアント認証情報のトークン交換）と OAuth リソースサーバーの検出に対応した、リモート Streamable-HTTP トランスポート。ツールレイヤーは両方のトランスポートで共有されます。
• 次の予定： HTTP トランスポートを external-api（Lambda + API Gateway NestedStack）にデプロイします。水平スケーリング用に、エッジでの JWT 検証と共有ストアのセッションをオプションで追加します。