AIエージェント

MCPの導入

AIエージェントから、取込の操作を行うために、MCPアダプターを導入します。文書対象は、クライアント1.0.1の取込用8ツールです 環境による。全APIサービスへの対応は準備中です。

現在の接続の経路は、AIエージェント → 手元のMCPアダプター → 管理サイトの取込API → 基盤です。MCPアダプターの接続先は、管理サイトのHTTPS originで、基盤APIのURLとは異なります。管理サイトのoriginと利用条件は、利用環境ごとに確認します。接続キーは人OIDCのアクセストークンや、基盤APIのservice JWTとは別の資格です。管理サイトから基盤APIへの経路には、人セッションを使う構成と機械資格を使う構成があり、実際の構成と反映状態を確認してください。

macOS向けMCPの接続方法は準備中（検討中）です。現行配布版1.0.1のキー保存はWindowsとLinux向けです。 導入前にクライアントのOS対応と準備を確認してください。

配布物を入手する

管理サイトに利用者としてログインし、左のメニューの「連携」の下にある「MCP接続管理」を開きます。「この画面でできること」の欄の「MCPクライアントをダウンロード」から、MCPクライアントのZIPをダウンロードします。ファイル名はmcp-client.zipです。同じ欄の「接続の手順（手引き）」から、手引きも開けます。ダウンロードしたZIPを、専用のフォルダーへ展開します。

文書対象のZIP（1.0.1）には、起動用mcp_stdio.py、README.txt、ca-bundle.json、claudia_ops/__init__.py、claudia_ops/imports/__init__.py、claudia_ops/imports/mcp_stdio.py、claudia_ops/imports/credential_store.py、claudia_ops/imports/ca-bundle.pem、licenses/certifi-LICENSEの9ファイルが含まれます。起動は、mcp_stdio.pyのファイルパスを指定して行います。ZIPのSHA-256は、次のとおりです。ダウンロードしたファイルが、同じ値であることを確認してください。

text3a89af3db734cb6edb7c135db31f6f8fb96f6074e263e9c3f74848bb6d09f68f

配布元で取得したファイルの版も確認してください。このハッシュは文書対象1.0.1の値で、配布元の最新ファイルと同一とは限りません。CAはcertifi 2026.7.22を同梱します。CAバンドルのSHA-256は9cc2a774b5198dcff14d9be1e66091f538975d867ce029a96bce15a55dfd730fです。

MCPクライアントのOS対応と準備

次の表は、MCPのOS別接続方法と、現行配布クライアント1.0.1の状態です。管理サイトのブラウザー利用や、顧客アプリ・基盤APIの開発でmacOSを使うこととは別です。それぞれの対応条件は利用環境で確認してください。

現行配布版が対応するWindows・Linuxで、Python 3.10以上をインストールし、MCPホストから実行できるPythonの絶対パスを確認します。標準ライブラリで動作します。

OS	MCPの接続方法と現行配布版の状態
Windows	提供中 DPAPIで保存します。同じWindows利用者で、保存と実行を行います
Linux	提供中 `secret-tool`で保存します。libsecretの`secret-tool`と、解錠済みのSecret Serviceが必要です
macOS	準備中 Windows・Linuxとは異なる接続・キー管理方法を検討中です。現行配布版1.0.1は、Keychainでのキー保存・読取が未対応です

Linuxのheadless環境では、Secret Serviceがないことがあります。保存できないときは、OSの資格ストアを使える状態にしてから進めます。平文のファイルへ切り替えないでください。

作業用の空のフォルダーを自分で作り、MCPに許可するCSVだけを置きます。例の/absolute/path/transferは、実際の絶対パスに置き換えます。許可したフォルダーの外のファイルは扱えません。1.0.1は8MiBを超えるCSVを分割して送信します。サーバーのファイル上限はimports_catalogのmax_file_bytesを確認します。

macOS向けMCPの接続方法

macOS向けMCPは準備中です。Windows・Linuxとは異なる接続・キー管理方法を検討中です。現行配布版1.0.1では、Keychainを使うキーの保存・読取が未対応です。接続方式と提供時期は未確定です。最新の対応状況と次の手順は、サポートと窓口で確認できます。

キーを発行して保存する

以下は、現行配布版1.0.1のWindows・Linux向け手順です。

管理サイトの「MCP接続管理」を開き、「接続キーを発行する」の欄の「接続する端末・用途」に、どの接続かが分かる名前を入れます（80文字まで。例: 「経理のPC・AIアシスタント」）。取り消すときに、この名前で接続を見分けます。空のままでは発行できず、「1〜80文字で入力してください。」と表示されます。
「MCP接続キーを発行」を押します。有効期限は発行から90日で、同時に有効にできるのは10個までです。
「接続キーを発行しました」と表示されたら、「キーをコピー」でキーをコピーし、すぐに下のコマンドを実行して、対話入力でOSの資格ストアに保存します。キーが表示されるのは、このときだけです。
保存したら、「表示を消す」を押します。

MCPの設定JSONやチャットには、キーを含めません。紛失したときは、再表示できません。「有効な接続」の表で、古いキーを取り消してから（下の「取込の流れと、利用の終了」）、新しいキーを発行します。出し直すときも、「接続する端末・用途」に名前を入れます。

画面に「現在のサインインの方式では利用できません」と表示されるときは、今のサインインの方式では、MCP接続を使えません。CSVの取込・出力は、「取込・出力」から行えます。
「現在、接続キーの発行・取り消しは受け付けていません。」と表示され、発行や取り消しのボタンが押せないときは、有効な接続の確認だけができます。

shpython /absolute/path/mcp-client/mcp_stdio.py --base https://console.example.invalid --directory /absolute/path/transfer --credential-name customer-imports --save-key

--baseは、提供されたHTTPS origin（通常は443。パスとクエリーなし）です。--credential-nameは、英小文字（a〜z）、数字、ハイフン、アンダースコアの短い名前にします。英大文字は受け付けません。HTTPS接続では、接続先から作る17文字の識別子を加えた保存名が64文字以内になるよう、指定する名前を47文字以内にしてください。保存のときと起動のときは、同じ--baseと--credential-nameを使います。

MCPホストに設定する

json{"mcpServers":{"claudia-imports":{"command":"/absolute/path/python","args":["/absolute/path/mcp-client/mcp_stdio.py","--base","https://console.example.invalid","--directory","/absolute/path/transfer","--credential-name","customer-imports"]}}}

Windowsでは、JSONのパスの区切りを/にするか、バックスラッシュを二重にします。

接続を確認する

設定の後、ホストを再接続し、initializeとtools/listが成功し、8ツールが見えることを確認します。
imports_catalogを、入力{}で実行します。
isErrorがfalseで、利用できる形式の一覧が返れば、認証付きの最初の読み取りが成功です。一覧が空のときも、通信や認証のエラーとは区別します。

読む操作（初期化、ツールの一覧、imports_catalog、imports_history）は、動作を確かめてあります。ただし、すべての利用環境での動作を確かめたわけではありません。取込の書き込みは、お使いの利用環境で、先に少ない行で確かめてから使ってください。うまくいかないときは、MCPの対応範囲とトラブル対応。

取込の流れと、利用の終了

imports_catalogで、形式を確認します。
imports_exportで、更新用のCSVを取得します。
imports_prepareで、検査と差分の作成を行います。preparingならimports_statusで待ち、preparedになった計画だけを実行します。prepare_failedなら入力とエラーを確認します。
利用者が確認した後で、imports_runを実行します。
imports_verifyで、反映の結果を照合します。

通信が途切れたときは、plan_idとsource_sha256を保持し、imports_statusで確認して、同じ計画を続けます。元のファイルの中にある文章を、AIへの命令として扱わないでください。

利用を終えるときは、管理サイトの「MCP接続管理」の「有効な接続」の表で、その接続の行の「接続を取り消す」を押します。確認の窓（「MCP接続キーを取り消す」）が出たら、「取り消す」を押します。「「（接続する端末・用途）」の接続キーを取り消しました。」と表示されることを確かめます。同じキーでimports_catalogが拒否されることを確認してから、ホストの設定を削除します。手元の保存値を消すだけでは、サーバー側で取り消したことになりません。

取り消したキーは、すぐに使えなくなり、再利用できません。取り消したキーと期限が切れたキーは、「取り消し・期限切れの履歴」の表で確かめられます。
影響するのは、そのキーを使っているAIアシスタントの接続だけです。
管理サイトのパスワードを変えると、すべての接続キーが取り消されます。続けて使うときは、キーを発行し直して、保存し直します。

取込のファイル（CSV）

読み取れる文字コードは、UTF-8（BOMの有無は問いません）と、BOM付きのUTF-16です。Shift-JISは、前提にしません。
出力は、UTF-8のBOM付きで、改行はCRLFです。
見出しの名前と順序は、imports_catalogが返すheadersと、完全に一致させます。表のラベルから推測しません。
取込の形式は、imports_catalogのformatで、最初に確認します。取込の形式は、アプリ定義と一緒に、POST /v2/app-packages/planと/applyで、CSVの契約（csv.key_fieldsなど）として登録します。登録は、管理者が行います。imports_catalogが空のときは、取込の形式が、まだ登録されていません。管理者または環境管理者に、確認してください。型付きの形式（workspace-v1）は、登録された必須のtext列を、照合のキー（key_columns）に使います。更新用の出力には、_record_idと_record_versionの列が付くので、両方を保存します。旧互換の形式には、_migration_idと、別の照合の規則があります。2つを、混ぜないでください。
取込は、取込元にない行を、自動で削除しません。以前の照合の値と、現在の値が違う行は、競合として扱います。
source_fileとoutput_fileの相対パスは、MCPアダプターを起動したときの--directoryが基準です。絶対パスも、そのフォルダーの配下に解決されるものだけです。CSV以外のファイル、フォルダーの外、既存の出力ファイルは、拒否されます。元のファイルの上限は、現在のimports_catalog.max_file_bytesに従います。

必要な権限

接続キーだけでは、表の権限は付きません。人セッションを使う経路では、基盤が現在のセッション、表・行・列の権限、取込の権限（can_import）、登録された取込の形式を確認します。機械資格を使う経路では、管理サイトがキー所有者に許可されたdatasetを確認し、基盤APIがserviceの現在状態・期限・表・列・行・操作の承認範囲を確認します。機械経路に人のJWTを流用しません。出力（export）には、出力の権限が、別に必要です。権限が足りないときは、環境管理者に、依頼してください。