Claude でアプリを作る｜SDK・API・MCP の使い分けと構成例

Claude でアプリを作る — 3 つの統合パス

Claude をアプリに統合する主な経路は次の 3 つです。それぞれ目的と習熟度に応じて選択します。

1. Messages API 直接呼び出し
HTTP POST で /v1/messages エンドポイントを叩く最もシンプルな方法です。curl や任意の HTTP クライアントで動作確認でき、特定言語に縛られない柔軟性があります。プロトタイプ検証・スクリプト処理・既存 HTTP ライブラリへの組み込みに向いています。

2. 公式 SDK（Python / TypeScript）
Anthropic が提供するライブラリを使い、型安全かつ簡潔なコードで統合します。エラー型・ストリーミング・非同期処理が標準実装されており、本番ユースケースの大半はこのルートです。

3. MCP（Model Context Protocol）
外部ツール・データベース・API を Claude に接続するオープンプロトコルです。ツール定義を JSON Schema で宣言し、Claude がタスクに応じて適切なツールを呼び出す複合ワークフローを構築できます。

選択の目安は「単発補完処理 → API 直接」「継続的なプロダクト開発 → SDK」「外部システムとの統合 → MCP」です。

Messages API の基本構造を理解する

Claude の核となる messages エンドポイント は、会話履歴を messages 配列で渡し、モデルが次の返答を生成するシンプルな設計です。

curl での最小リクエスト例:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "あなたは日本語対応のカスタマーサポートです。",
    "messages": [
      {"role": "user", "content": "返品手続きを教えてください"}
    ]
  }'

押さえるべき主要パラメータは以下の 4 つです。

system を messages 配列内に入れる誤実装が多発しているため、公式仕様どおりトップレベルで渡す点に注意してください。

Python SDK での実装パターン

Python SDK は pip install anthropic でインストールし、数行で動き始めます。

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY を自動参照

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="あなたは製品に詳しいサポート担当者です。",
    messages=[
        {"role": "user", "content": "このエラーの原因を教えてください"}
    ]
)
print(message.content[0].text)

ストリーミングが必要な場合は stream=True を追加するだけでチャンク応答に切り替わります。非同期処理は AsyncAnthropic クライアントで対応できます。

本番実装では以下の 2 種の例外を必ず捕捉し、指数バックオフを実装してください。

1. anthropic.RateLimitError（429）— レート上限到達。数秒待ってリトライ
2. anthropic.BadRequestError（400）— 入力トークン超過や不正なリクエスト形式

import time, anthropic

client = anthropic.Anthropic()

def call_with_retry(messages, retries=3):
    for attempt in range(retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=messages,
            )
        except anthropic.RateLimitError:
            if attempt < retries - 1:
                time.sleep(2 ** attempt)
    raise RuntimeError("最大リトライ回数を超過しました")

TypeScript / Node.js SDK の構成

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // ANTHROPIC_API_KEY を自動参照

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "あなたはコードレビュー担当のエンジニアです。",
  messages: [
    { role: "user", content: "このコードを改善してください: ..." }
  ],
});

console.log(message.content[0].text);

npm install @anthropic-ai/sdk で Node.js 18+ に対応します。Python SDK と同じパラメータ設計のため、どちらかを習得すれば移行コストはほぼゼロです。

Cloudflare Workers / Vercel Edge などの Edge Runtime でも動作しますが、ストリーミング API の挙動はランタイムごとに差異があるため、初回は Node.js 標準環境で検証することを推奨します。

MCP でツール連携を拡張する

MCP（Model Context Protocol）は Claude が外部ツールを呼び出すための標準インターフェースです。Anthropic が 2024 年に公開したオープンプロトコルで、データベース・API・ファイルシステムへのアクセスを宣言的に定義できます。

MCP を使ったツール連携の基本フローは次のとおりです。

1. MCP サーバーを実装するか、コミュニティ提供のサーバー（Supabase・GitHub・Slack 等）を採用する
2. リクエストの tools パラメータにツール定義（名前・説明・JSON Schema）を渡す
3. Claude が tool_use ブロックを返したら、サーバー側でツールを実行する
4. 実行結果を tool_result として messages に追加し、Claude に再送する
5. Claude が最終回答を返すまでループを繰り返す

このパターンにより、「ユーザーの質問 → データベース検索 → 結果を基に回答生成」のような複数ステップの処理を Claude が自律的に組み立てるパイプラインを構築できます。

ツール定義の例（天気取得）:

{
  "name": "get_weather",
  "description": "指定した都市の現在の天気を返します",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "都市名（例: Tokyo）"
      }
    },
    "required": ["city"]
  }
}

ツール呼び出しを使った自律処理パイプライン

Anthropic Academy の「Build with Claude」 では、単発のメッセージ処理を超えた自律処理ワークフローの構築方法が体系的に解説されています。

Messages API と MCP ツールを組み合わせると、単一のプロンプトで完結しない複雑なタスクを扱えます。具体的には以下のような構成が可能です。

• リサーチ支援: 「競合他社を調査して表にまとめて」→ Web 検索 → 情報収集 → テーブル生成
• コード生成 + テスト: 「この仕様を実装して」→ コード生成 → テスト実行 → エラー修正
• データ分析: 「売上データを分析して」→ DB クエリ → 集計 → グラフ用データ生成

ポイントは タスクの粒度を明確に定義すること です。Claude にとって曖昧な目標より、「何を使って何を返すか」が明確なツール定義の方が精度の高いアウトプットが得られます。

モデル選択: Haiku・Sonnet・Opus の使い分け

Claude には用途に応じた 3 つのモデル系統があります。

アプリ開発では 初期段階を Sonnet で構築し、コスト最適化フェーズで高頻度エンドポイントを Haiku に切り替える 段階的移行が一般的です。Opus は全リクエストに使うのではなく、精度が特に重要な処理だけに絞ると費用対効果が高まります。

モデル ID は claude-sonnet-4-6（Sonnet 最新）のようにバージョン付きで指定することで、予期しない動作変更を防げます。

本番投入前のコスト削減策

本番運用に移る前に実装しておくと効果が大きい 3 つのコスト対策を紹介します。

プロンプトキャッシュ（最大 90% 削減）
繰り返し渡す長いシステムプロンプトや参照文書には、cache_control を付与してキャッシュヒットさせることで入力コストを最大 90% 削減できます。同じシステムプロンプトを 1 日数千回送るユースケースでは投資対効果が非常に高くなります。

バッチ API（50% 削減）
レスポンスの即時性が不要な処理（夜間バッチ・定期レポート等）は Message Batches API に流すことで通常料金の 50% で実行できます。結果は非同期で取得します。

Haiku への分散
分類・ラベリング・簡単な要約などの低複雑度タスクを Haiku に振り分けるだけで、Sonnet 比で 1/20 以下のコストになる処理があります。タスク種別ごとにモデルを分けるルーティング層を設けることが本番運用の標準構成です。

本番投入チェックリスト

次の 7 点を確認してから本番に移してください。

1. API キーを .env などの環境変数で管理し、コードやリポジトリにハードコードしていないか確認する
2. max_tokens を適切に設定し、上限超過による 400 エラーを防ぐ
3. 指数バックオフ付きのリトライロジックを実装する（429 / 529 エラー対応）
4. プロンプトキャッシュを有効化して繰り返しのシステムプロンプトコストを削減する
5. 高頻度・低複雑度の処理を Haiku や Batches API に振り分けるルーティングを設計する
6. レート制限（RPM / TPM）をモニタリングし、急激なリクエスト増加に対応できる分散策を取る
7. ログに API キーや個人情報が出力されないよう、マスキング処理を施す

これらを事前に実装することで、スパイクトラフィックや予期しない入力による障害リスクを大幅に下げられます。公式の Building with Claude ドキュメントには詳細な API リファレンスと実装サンプルが常時更新されているため、実装前の参照を推奨します。