Claude が社内 API を使う方法は一つではありません。MCP は再利用できる tool contract を作るときに有効ですが、API 設計、認可、承認、監査ログの代わりにはなりません。
最初に決めるべきことは protocol ではなく、誰が実行を所有するかです。アプリケーションが prompt、user session、権限確認、tool execution、retry、audit log をすでに持っているなら、Claude API の direct tools が最短です。複数の Claude surface で同じ内部 toolset を使いたいなら、狭い remote MCP server を設計します。
2026年6月1日時点で、Anthropic のドキュメントは direct tool use、Messages API の MCP connector、Claude Code MCP、Claude custom connectors を別の surface として扱っています。まず次の表で分けてください。
| 連携で必要なこと | 最初に選ぶもの | 理由 |
|---|---|---|
| 1つのアプリが prompt、state、execution、audit を持つ | Claude API direct tools | アプリが tool_use を受け取り、内部 API を実行し、tool_result を返せる。auth boundary はアプリ内に残る。 |
| Messages API から再利用可能な remote toolset を呼びたい | Claude API MCP connector | アプリ内に MCP client を実装せず、Claude が reachable remote MCP server に接続できる。 |
| 複数の Claude clients が同じ内部ツール契約を共有する | Custom MCP server | API/platform team が tool name、schema、auth、output limit、review を一箇所で管理できる。 |
| 開発者がローカル repo、script、machine workflow を扱う | Claude Code MCP | local stdio、project scope、user scope、/mcp は developer workflow の領域。 |
| Claude.ai や Desktop の人間向け workflow で承認済み tool を使う | Custom connector | user-facing connector route であり、network、plan、permission、trust boundary が別にある。 |
| 長時間の hosted agent runtime が本当の課題 | Managed Agents | tool access ではなく hosted session runtime が主問題のときだけ検討する。 |
停止ルール：MCP が使えるからといって MCP server から始めないでください。reuse、connector ownership、cross-client consistency が追加の server、auth、review surface に見合うときだけ MCP にします。
Direct Claude API Tools と MCP の境界
もっとも短い実装は Claude API の tool use です。アプリが tool definitions を渡し、Claude が必要なときに tool_use を返し、アプリの backend が権限を確認して内部 API を実行し、tool_result を返します。1つの product app が user session、tenant、service account、retry、logging、final response を管理しているなら、このルートが自然です。
MCP が必要になるのは、tool contract を1つの app の外に出したいときです。たとえば search_support_ticket、get_customer_billing_summary、create_refund_draft、summarize_incident_errors を Messages API、Claude Code、Claude.ai connector、将来の internal agent で同じように使いたい場合、MCP server が bounded interface になります。
| 判断点 | Direct Claude API tools | MCP または remote connector |
|---|---|---|
| 実行の owner | 1つの app が loop を持っている | 複数 client が tool contract を共有する |
| tool execution | app が実行して tool_result を返せる | remote server が protocol boundary の後ろで実行を持つ |
| auth boundary | app session と service account で足りる | connector header、OAuth、allowlist、per-tool permission が必要 |
| change control | 1つの product team が更新できる | platform/API team が stable contract を持つ |
| operational cost | 第一版を小さく保てる | server、deploy、monitoring、review、rollback を受け入れる |
実用的なしきい値は reuse と ownership です。単一 product workflow だけで使う tool なら direct tools が速く、安全で、レビューしやすいことが多いです。複数 client が同じ operation を使うなら、MCP によって実装の重複と contract のばらつきを減らせます。
MCP tools を backend endpoints の薄いコピーにしないでください。Claude は admin API 全体を必要としていません。必要なのは「請求状態を要約する」「返金草稿を作る」「事故ログの上位エラーをまとめる」のような task-shaped capability です。tool name、description、input schema、returned content は Claude が選択するための interface なので、広すぎる tool は不安定で危険です。
内部 API は狭い wrapper にする
安全な Claude 内部ツール連携は、社内 API をそのまま外に出すことではありません。まず wrapper layer を置き、既存 API を少数の task-shaped tools に変換します。各 tool は明確な inputs、bounded outputs、scoped credentials、predictable errors、audit trail を持つべきです。
endpoint からではなく、ユーザーの成果から逆算します。
| 目的 | 悪い tool 形状 | よい tool 形状 |
|---|---|---|
| 顧客の billing status を確認する | call_internal_billing_api が任意 path と body を受ける | get_customer_billing_summary が customer_id と reason を受け、status、invoice、next action を返す |
| refund を準備する | admin_mutation が raw JSON を受ける | create_refund_draft が draft id を返し、実行前に approval を要求する |
| incident を調査する | query_logs が無制限 time range を受ける | summarize_incident_errors が service、time window、limit、count、sample を返す |
| CRM note を追加する | write_crm が任意 endpoint を許す | append_account_note が account id、note、reason、actor、audit id を要求する |
wrapper は Claude に見せないものも決めます。secrets、tokens、raw PII、database rows、unlimited logs、大きな documents は default で返さないでください。Claude が必要としているのが判断なら、source ids、counts、timestamps、warnings、small samples を含む decision-ready summary を返します。
compact output は後からの最適化ではなく tool design の一部です。大きな payload は context を消費し、ノイズの多い fields や重複 metadata を Claude に読ませます。よい result は短く、typed で、次の decision に使いやすい形です。
json{ "customer_id": "cus_123", "billing_status": "past_due", "open_invoice_count": 2, "latest_invoice": { "id": "inv_789", "amount_due_usd": 42.5, "due_date": "2026-06-03" }, "recommended_next_action": "ask customer to update payment method", "source_records": ["inv_789", "ticket_456"] }
write actions は read より遅く、狭く、監査しやすくしてください。最初は read-only summary を証明します。次に draft や preview を作ります。最後に approval の後ろで実行します。risk のある action には reason、idempotency key、approval id、actor、final state verification、可能なら rollback path が必要です。
prompt injection も内部ツールの問題です。support ticket、CRM note、document、email、web page、user upload には、Claude に policy を無視させる指示が混ざることがあります。tool result は untrusted data として扱い、必要のない raw text を返さず、structured summary を優先します。
Remote Connector の境界：API MCP Connector、Custom Connectors、Network Reach
Claude API MCP connector は local Claude Code MCP server ではありません。Messages API から remote MCP servers に接続する route です。server は Streamable HTTP または SSE を使う HTTP endpoint として reachable である必要があります。local stdio server はこの API connector route に直接つながりません。
2026年6月1日時点の planning boundary は次の通りです。
| 境界 | 実装への影響 |
|---|---|
| beta header | current request は anthropic-beta: mcp-client-2025-11-20 を要求する。古い header は再確認する。 |
| transport | API connector は remote HTTP/SSE を想定する。Claude Code の local stdio command をこの path に貼らない。 |
| capability scope | 現時点では MCP tool calls が中心で、すべての MCP primitive を通す万能 tunnel ではない。 |
| data retention | Docs は MCP connector が ZDR の対象外と説明しているため、sensitive data は別途 review が必要。 |
| tool control | allowlist、denylist、toolset controls で、task に必要な tools だけを見せる。 |
Claude.ai や Claude Desktop の custom connector は別の user-facing route です。こちらも remote MCP を使いますが、product surface、user approval、admin controls、plan availability、network requirement が backend Messages API integration とは異なります。Anthropic cloud infrastructure が connector に到達できる必要があるため、private network の中で動く demo だけでは production design になりません。
内部 API では、この network boundary が deployment、firewall、OAuth、service token、tenant boundary、admin approval を決めます。内部 system を読む、または変更できる connector は、外部 integration endpoint と同じ security review を受けるべきです。
| 質問 | Direct tools | API MCP connector | Custom connector |
|---|---|---|---|
| 内部 system にアクセスするのは誰か | app backend | Claude API path から reachable な remote MCP server | Claude user surface から reachable な remote MCP server |
| auth はどこで enforce するか | app session、tenant policy、service account | MCP server、connector config、headers、internal policy | user/admin approval、connector auth、MCP server、internal policy |
| よい第一用途 | product-owned workflow | Messages API 用の shared internal toolset | 承認済み human Claude workflow |
| 最初のリスク | app code 内の hidden broad execution | too many tools、too much data | user permission、write actions、prompt injection |
remote MCP server は production service として設計します。health check、request log、auth verification、rate limit、schema test、typed error、result-size limit、safe failure response が必要です。開発者1人の local helper なら Claude Code branch に残してください。
Claude Code と Desktop はローカル workflow branch
Claude Code MCP は local developer workflow に向いています。repo tools、project scripts、internal docs search、issue tracker、read-only database helper、browser verification、team utility などです。local stdio、project scope、user scope、/mcp はこの branch のものです。
しかし Claude Code settings は production app の tool surface ではありません。production app が Messages API を呼ぶなら、developer laptop の .mcp.json は API connector になりません。stdio server が local で動いた事実は local workflow branch の証明であり、remote reachability の証明ではありません。
local workflow は次のように確認できます。
bashclaude mcp add --scope project support-search --transport stdio -- ./scripts/support-search-mcp claude mcp list
remote path は deployed service として考えます。
bashclaude mcp add --scope project support-search https://mcp.example.com/mcp
この2つは文書でも runbook でも分けてください。local stdio は local file system、local commands、developer-specific credentials に依存できます。remote HTTP server には deployment、TLS、auth、observability、stable interface が必要です。この前提を混ぜると、demo は動くが production approval が通らない system になります。
Claude Code の MCP server 選びなら Claude Code のおすすめ MCP servers を使ってください。設定が増えすぎて context が重いなら Claude Code MCP context overload を見てください。credentials、provider route、base URL が問題なら Claude Code API configuration が該当します。
Production Safety Checklist
内部 tools は safety ladder を通します。第一版は Claude が bounded data を読んで useful summary を返せることを証明します。write access は preview、approval、audit、verification が揃ってからです。
| Gate | Pass condition | Stop if... |
|---|---|---|
| Tool scope | 各 tool が1つの outcome と1つの narrow operation に対応する | arbitrary endpoint、SQL、shell、mutation を受ける |
| Credential scope | credentials は server-side、least privilege、environment 別 | Claude が secrets を見られる、または broad admin credentials を使える |
| Read-only proof | reads が source ids 付き compact results を返す | raw dumps、secrets、unlimited rows を返す |
| Write preview | writes は draft または preview から始める | approval なしで即実行する |
| Approval path | risky actions が approver、reason、audit id を記録する | approval が prompt text にしか存在しない |
| Audit log | actor、user、tool、input summary、output summary、result id を記録する | Claude が何を試したか復元できない |
| Output budget | limit、pagination、summary、handle を default にする | 1回の call が logs、rows、documents で context を埋める |
| Prompt guard | tool results を untrusted data として扱う | retrieved content が policy bypass を指示できる |
approval design は risk に合わせます。billing summary は auth と logging で足りるかもしれません。refund、deployment、permission change、account suspension、database mutation は preview、approval record、final state check が必要です。rollback がない domain では、approval 前にその事実を明示します。
audit log は compliance だけのためではありません。model がどの tool を選んだか、どの parameters を渡したか、permission check がなぜ通ったか、internal API result がどれくらい大きかったか、Claude がどう解釈したかを debug するために必要です。
Implementation Sketch
direct tools でも MCP でも pattern は同じです。narrow tool を定義し、trusted code で実行し、compact output を返し、attempt を log します。違うのは contract がどこにあり、どの runtime が handler を呼ぶかです。
direct Claude API tools では app loop が execution を持ちます。
tsconst tools = [ { name: "get_customer_billing_summary", description: "Return a compact billing summary for a support-approved customer id.", input_schema: { type: "object", properties: { customer_id: { type: "string" }, reason: { type: "string" } }, required: ["customer_id", "reason"] } } ]; // 1. request に tools を含める。 // 2. Claude が tool_use を返したら caller permission を確認する。 // 3. scoped service credential で internal API を呼ぶ。 // 4. compact tool_result を返し、audit entry を書く。
remote MCP server では API team が server contract を持ちます。server は tool definitions と handlers を公開し、Claude clients は選んだ product surface から接続します。第一版は退屈なくらい明確にします。
| Server design choice | Better default |
|---|---|
| Tool naming | verb plus domain outcome、例：get_customer_billing_summary |
| Input schema | required ids、reason、time windows、limits、enum values |
| Output schema | summary fields、source ids、next action、warnings、cursor |
| Error handling | raw stack trace ではなく typed domain errors |
| Observability | tool call id、actor id、request id、latency、result size、policy decision |
| Permissions | default read-only、write tools は explicit approval の後ろ |
API MCP connector を使うなら、server が持つ全 tools を出さず、task に必要な small toolset に絞ります。custom connectors なら user consent と admin controls を確認します。Claude Code なら config を正しい scope に置き、secrets を commit しないでください。
次に何をするか
次の行動は execution owner で決まります。
| 現在の状況 | 次の一手 |
|---|---|
| 1つの app が少数の internal reads だけ必要 | direct Claude API tools を実装し、compact tool_result と audit log を作る。 |
| 複数 Claude clients が同じ toolset を使う | read-only tools から custom MCP server を設計し、API MCP connector など承認済み surface に接続する。 |
| local developer automation が主目的 | Claude Code MCP に残し、scope を明示し、context load を監視する。 |
| Claude.ai/Desktop の human workflow が目的 | custom connector の permission、plan、network、admin control を設計する。 |
| 難しいのは hosted long-running runtime | 自前 loop の前に Claude Managed Agents と比較する。 |
最初の milestone は read-only end-to-end proof です。model request、tool selection、auth check、internal API call、compact result、audit log、human-visible answer が通ることを確認します。その後に allowlist、output caps、approval、write preview を加えます。reuse が必要になってから MCP server に昇格させます。
よくある質問
Claude を内部 API につなぐには MCP が必須ですか？
必須ではありません。1つの app が loop を所有し、tool call を実行できるなら direct Claude API tools で十分なことが多いです。MCP は複数 client や connector surfaces で同じ tool contract を再利用したいときに有効です。
Direct Claude API tools と API MCP connector は何が違いますか？
direct tools では app が tool_use を受け取り、internal operation を実行し、tool_result を返します。API MCP connector では Messages API が remote MCP server に接続し、その server が tool interface を持ちます。後者は server と network boundary を増やすため、reuse の理由が必要です。
API MCP connector は local stdio MCP server を直接使えますか？
直接は使えません。2026年6月1日時点では、API connector は remote HTTP/SSE MCP server を要求します。local stdio は Claude Code または local Desktop-style workflow の領域です。
内部 API 全体を MCP tools として公開してよいですか？
よくありません。task-shaped tools、narrow schemas、compact outputs にしてください。arbitrary endpoint、SQL、shell、admin mutation は Claude にとっても人間の review にとっても危険です。
write actions はどう設計すべきですか？
まず read-only tools から始めます。write は draft または preview を返し、reason、actor、idempotency key、audit id、approval、final verification を要求します。high-risk action は prompt だけで即実行してはいけません。
MCP tool results は context size に影響しますか？
影響します。tool definitions、tool calls、tool results はすべて context に入ります。summary、filter、pagination、source ids を使い、raw payload が不要なら handle や record id を返します。
Claude Code MCP はどこで使うべきですか？
Claude Code MCP は local developer workflow に向いています。project scripts、repo helpers、local automation、read-only helper などです。production Messages API connector の deployment、network、auth、audit の代わりにはなりません。
production 前に最低限何を確認しますか？
route owner、server reachability、beta header または connector requirement、auth scope、tool allowlist、read-only result shape、write approval、audit logging、output limits、prompt-injection handling を確認します。不明点があるなら read-only pilot に止めます。