MCP連携（Claude / Copilot）

MCPとは

MCP（Model Context Protocol）は、AI クライアントが外部ツールを呼び出すための共通プロトコルです。TOKIUM契約管理は tokium-contract-mcp という MCP サーバを提供しており、これを AI クライアントに接続すると、自然言語のまま契約書の検索・参照・編集ができます。

tokium-contract-mcp は公開API（/api/v1）への薄い変換レイヤーで、各リクエストに API キーを付けて API を呼び出します。

提供ツール

ツール	対応API	説明
search_contracts	GET /contracts	契約書を検索・一覧（query / status / folder_uuid / 締結日などで絞り込み）
get_contract	GET /contracts/:uuid	契約書を UUID 指定で1件取得
update_contract	PATCH /contracts/:uuid	契約書を編集（指定フィールドのみ部分更新）
list_folders	GET /folders	アクセス可能なフォルダ一覧（name 部分一致で絞り込み可）
find_folder	GET /folders/search	フォルダ名の完全一致検索（folder_uuid の特定用）

接続方式の違い

クライアント	接続方式	状態
Claude Code	ローカル stdio	✅ 利用可能
VS Code GitHub Copilot	ローカル stdio	✅ 利用可能
Copilot Studio / Microsoft 365 Copilot	リモート HTTPS + OAuth	⏳ リモートモード（WIP）完成後

ローカル stdio 方式は、tokium-contract-mcp を同じ PC 上のプロセスとして起動するため、同一 PC で動くクライアント（Claude Code / VS Code）から接続できます。クラウド系（Copilot Studio など）はインターネット越しに HTTP 接続するため、リモート（Streamable HTTP）モードが必要です。

事前準備

1. API キーを発行する（「ユーザー設定 > API キー」、ktk_ で始まるトークン）
2. tokium-contract-mcp をビルドする（npm install && npm run build）

Claude Code への接続

claude mcp add コマンドで登録します（local スコープの例）。

claude mcp add tokium_contract -s local \
  -e TOKIUM_CONTRACT_API_BASE_URL=https://contract.keihi.com \
  -e TOKIUM_CONTRACT_API_KEY=ktk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -- node /absolute/path/to/tokium-contract-mcp/dist/index.js

• 設定は ~/.claude.json の該当プロジェクト配下に保存されます（local スコープはそのプロジェクトでのみ有効）。
• 登録後、Claude Code を再起動するとツールが読み込まれます。
• /mcp で接続状態を確認できます（tokium_contract · ✔ connected · 5 tools）。

VS Code GitHub Copilot への接続

Claude Code と同じローカル stdio 方式です。設定ファイルの場所だけが異なります。

プロジェクトルートに .vscode/mcp.json を作成します。

{
  "servers": {
    "tokium_contract": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/tokium-contract-mcp/dist/index.js"],
      "env": {
        "TOKIUM_CONTRACT_API_BASE_URL": "https://contract.keihi.com",
        "TOKIUM_CONTRACT_API_KEY": "ktk_..."
      }
    }
  }
}

⚠️ .vscode/mcp.json は Git にコミットされるため、API キーを直書きしないでください。VS Code の inputs（起動時に入力させる）機能を使うか、コマンドパレットの MCP: Add Server からユーザー設定に登録すると、キーが Git に乗りません。

接続後、Copilot Chat を Agent モードに切り替え、ツール一覧から tokium_contract を有効化すると、チャットから「契約書を検索して」などと指示できます。

リモートモード（Streamable HTTP）— WIP

ローカル（stdio）と同じツールを HTTP transport で公開するモードです。各リクエストの Authorization: Bearer <token> をそのまま公開API へ転送するため、固定 API キーを持ちません（トークンはクライアントが OAuth で取得）。

• POST /mcp … MCP エンドポイント（要 Bearer。無ければ 401）
• GET /.well-known/oauth-protected-resource … 認可サーバ発見用メタデータ

Copilot Studio / Microsoft 365 Copilot などのクラウド系クライアントに接続するには、このリモートモード + OAuth 認可サーバ + 公開 HTTPS デプロイが必要です。現時点では準備中（WIP）のため、クラウド系からの接続は未対応です。

環境変数

変数	必須	説明
TOKIUM_CONTRACT_API_BASE_URL	✓	API のベースURL（末尾スラッシュ不要）
TOKIUM_CONTRACT_API_KEY	ローカル時	ktk_ で始まる API キー（stdio モードのみ）
PORT	-	リモートモードの待受ポート（既定 3333）