ClaudeとDeelを連携する方法 — 海外採用のコスト試算と書き込みの線引き

Claude Deel連携とは何か

Deel ConnectorはClaudeをDeelのアカウントにつなぎ、契約・支払い・休暇・給与計算・HRISのデータを自然文で扱えるようにする公式連携です。開発元はDeel自身で、Connectorsディレクトリでは「Anthropic verified」の表示が付き、カテゴリーは「Financial services」です。サインインは必須で、接続先のURLは https://api.letsdeel.com/mcp です。

公開されているツールは95個あります。契約の作成、休暇申請、請求書の調整、労働許可の要件確認まで広く並び、海外採用の試算に使う calculate_employment_cost や calculate_eor_versus_entity_hiring_costs もその一部です。つまりこのConnectorは「調べるだけ」では終わらず、Deel上のレコードを書き換える道具も同じ窓口に入っています。

この記事は、95個のうち採用コストの試算に使う系統と、契約変更・支払いを動かす系統を分けて見ていきます。Connectorの一般的な仕組みはConnectorsの解説にあります。契約書そのものを扱う連携ならDocuSignやIroncladが別の役割を持ちます。

接続手順 — claude.aiとClaude Code

claude.aiでは「Customize > Connectors」を開き、「+」ボタンからDeelを探して接続を始め、Deelのログイン画面へ進みます。認証はOAuth2で、同意画面で権限を確認して許可します。

Claude Codeからは、リモートHTTPサーバーを追加する通常のコマンドで足ります。

claude mcp add --transport http deel \
  https://api.letsdeel.com/mcp

追加後にClaude Code内で /mcp を開き、Deelの認証を済ませます。OAuth2に対応していないクライアントでは、Deelのダッシュボードで発行する個人アクセストークン(PAT)を Authorization: Bearer ヘッダーで渡す方法もあります。発行場所は「More」→「Developer」→「Apps」→「Generate token」です。トークンはバージョン管理に入れず、環境変数か秘密情報の管理ツールに置きます。

認証まわりの数字も押さえておきます。

Deelの公式ドキュメントは、OAuth2なら同意の取り消しをトークンの再発行なしで行えると説明しています。PATは対応していないクライアント向けの代替という位置づけです。

接続直後に確かめること

接続できたかどうかは、Deelの案内にある簡単な依頼で確かめられます。「Deelの契約を一覧にして」「利用できる休暇ポリシーは」「組織の情報を見せて」の3つです。ツールが呼ばれて結果が返れば、接続は成功しています。

認証の挙動には少し癖があります。initialize と tools/list は認証なしで通り、保護された操作を呼んだ時点で初めて401が返って認証の流れが始まります。ツールの一覧は見えるのに、実行すると認証を求められる状態は、故障ではなく仕様どおりの動きです。Publicの参照データ(対応国や通貨の一覧)だけなら、認証前でも取得できる設計になっています。

リフレッシュトークンは1回限りなので、自作のクライアントで更新のたびに新しい値を保存し損ねると、次の更新が invalid_grant で失敗します。claude.aiやClaude Codeのような既製のクライアントでは、この更新は自動で行われます。

試算系ツール — 海外採用のコストを会話で比べる

Deelのドキュメントは、コスト試算に使う系統を「Hiring intelligence」として分類しています。名前と説明は次のとおりです。

Deelのリファレンスではキャメルケース(calculateEmploymentCost など)、Connectorのページではスネークケースで表記されています。Claudeが実際に見るツール名はClaude Codeの /mcp で確認できます。

EOR(Employer of Record)は、現地に法人を持たずに、Deelなど雇用代行会社を通じて海外の人材を雇う仕組みです。現地法人を設立して直接雇う方法と比べて、どちらが割に合うかは国と人数で変わります。この比較を1回の依頼にまとめられるのが calculate_eor_versus_entity_hiring_costs の使いどころです。

依頼の書き方の例です。以下は試算を頼む文面の一例で、返ってくる結果はDeel側の計算に依存します。

ポルトガルでシニアエンジニアを1名雇う想定で、
年収8万ユーロの場合のEORと現地法人の雇用コストを
比較して。ビザ要件も確認して。

国・職種・年収・通貨を具体的な値で渡すと、前提の食い違いを避けやすくなります。前提を数字で渡したほうが、Deelの計算結果も読み違えにくくなります。

Claudeは計算結果を要約して説明できますが、試算の中身はDeelが返した値です。稟議に使う数字は、Deelの画面で同じ条件を入れ直して照合すると安心です。試算系のツールがどの権限スコープを要求するかは、公式ドキュメントに個別の記載がありません。

書き込み系ツール — 契約変更とオフサイクル支払い

ここから先は、Deel上のデータを実際に変える系統です。ツールの説明文から、次のものが書き込みにあたると読み取れます。

Deelのドキュメントは、各ツールを読み取り・書き込みで区分けしていません。この表は、ツール名と説明文からの分類です。手がかりになるのは、認可のスコープです。公式の一覧には contracts:read と contracts:write、invoice-adjustments:read と invoice-adjustments:write のように、読み取りと書き込みが別のスコープとして載っています。contracts:write は契約の作成と変更の両方を含むと説明されているため、新規作成だけを許したい、といった細かい切り分けはスコープ単位ではできません。ここは権限ルールの ask で補います。

オフサイクル支払いは、給与や契約の通常の支払い日とは別に、個別の支払いを追加する操作です。Deelのリファレンスには、追加用のツールに加えて、契約ごとの取得用ツール(getOffCyclePaymentByContractId、getOffCyclePaymentsByContractId)が並んでいます。追加の前に既存の一覧を読ませれば、二重に登録する事故を減らせます。

書き込みの前に人の確認を挟む設定

Claude Codeなら、書き込み系のツールだけ毎回確認を求める設定にできます。権限ルールは mcp__<サーバー名>__<ツール名> の形で、サーバー名は上のコマンドで付けた deel です。

{
  "permissions": {
    "ask": [
      "mcp__deel__amend_contract",
      "mcp__deel__add_off_cycle_payment_for_contract",
      "mcp__deel__create_invoice_adjustment"
    ]
  }
}

ツール名は上の例ではConnectorのページの表記に合わせています。実際のツール名が異なる場合は、/mcp で表示された名前に置き換えてください。この形のルールの書き方はMCPの権限構文の解説にまとめてあります。全部をaskにするのではなく、金額や契約条件が動くものに絞ると、確認の回数が増えすぎません。

claude.aiでは、Connectorの設定画面(Customize > Connectors)でツールの種類ごと、または個別のツールごとに「Always allow」「Needs approval」「Blocked」を選べます。書き込み系を「Needs approval」にすれば、Claude Codeの ask と同じ働きになります。加えてDeelの側でも、同意の段階で許可するスコープを絞れます。Deelは最小権限の原則を勧めており、読み取りだけで足りるなら contracts:read のような読み取りスコープに限定するよう案内しています。

試算と契約変更のあいだにあるツール群

95個のツールは、Deelのリファレンスでは領域別に分かれています。採用の意思決定から契約、支払い、入社後の管理まで、順に並べると次のとおりです。

試算の前後をつなぐ使い方が、この表の読みどころです。たとえば、calculate_eor_versus_entity_hiring_costs で比べたあとに、EORの追加コストと最短の開始日を続けて確認できます。国別の採用ガイドと給与分布を先に読ませれば、年収の前提を置く段階から会話で詰められます。

Connectorのページには、分析タイル(create_analytics_tile)やワークフローの追加(add_workflow_trigger、add_workflow_actions)といったツール名も並んでいます。ただし、それぞれが具体的に何を返し、何を書き換えるのかは、今回参照した公式ページには説明がありません。名前から用途を決めつけず、使う前にDeelのAPIドキュメントで確認します。

権限レベルは3種類

Deelは、ツールを3つの権限レベルに分けています。

採用コストの試算は、組織の内部データを見せなくても意味のある結果が出ます。一方で契約変更や支払いは組織レベルの権限が前提になります。誰のアカウントでConnectorを接続するかで、Claudeが動かせる範囲は変わります。人事の管理者アカウントで接続するなら、書き込み系の ask ルールが特に効きます。

使い分けの早見表

目的別に、Claudeへ任せる範囲を分けると次のようになります。

権限の切り方は、読み取りだけを渡す段階から始めて、書き込みを足していく順が安全です。最初の1週間は試算と一覧取得だけで使い、契約変更は人が画面で実行する運用にしておけば、Claudeの誤解釈が支払いに届く経路がありません。

接続のトラブルと制限

Deelの公式ドキュメントが挙げる、接続まわりの症状と原因は次のとおりです。

ツールが多いぶん、依頼が曖昧だとClaudeが複数のツールを順に呼びます。Deelも「EOR契約を一覧にして」のように対象を絞る書き方を勧めています。429が返ったら Retry-After に従います(Deelのベストプラクティスの記載)。

もう一つ、Connectorの一覧ページには「Anthropicは開発元が提供するツールを管理しておらず、想定どおり動く保証はできない」旨の注意書きがあります。ツールの一覧や挙動は、Deel側の更新で変わりえます。

まとめ

DeelのConnectorは、海外採用のコスト試算という読み取りに近い使い方と、契約変更・オフサイクル支払いという書き込みの使い方が、同じ接続の中に同居しています。試算は数字の照合さえすれば、会話で回せる作業です。書き込みは、Claude Codeなら ask ルール、claude.aiならConnectorのツール権限とDeel側のスコープで、人の確認を残す形が扱いやすくなります。