Building Apps with Claude | Choosing Between SDK, API, and MCP with Configuration Examples

Building Apps with Claude — 3 Integration Paths

There are three main paths for integrating Claude into your app. Choose based on your goals and level of expertise.

1. Direct Messages API Calls
The simplest approach: send an HTTP POST to the /v1/messages endpoint. You can test it with curl or any HTTP client, and it isn't tied to any specific programming language. This is ideal for prototype validation, scripting, or embedding into existing HTTP libraries.

2. Official SDK (Python / TypeScript)
Use Anthropic's libraries to integrate Claude with type-safe, concise code. Error types, streaming, and async processing are built in, making this the go-to route for the vast majority of production use cases.

3. MCP (Model Context Protocol)
An open protocol for connecting external tools, databases, and APIs to Claude. You declare tool definitions using JSON Schema, and Claude calls the appropriate tools autonomously based on the task. This enables building complex multi-step workflows.

As a rule of thumb: "one-off completion → direct API," "ongoing product development → SDK," "external system integration → MCP."

Understanding the Basic Structure of the Messages API

The core messages endpoint of Claude is straightforward: pass the conversation history as a messages array, and the model generates the next response.

Minimal request example with 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": "返品手続きを教えてください"}
    ]
  }'

Here are the four key parameters to understand:

A common mistake is placing system inside the messages array — make sure to pass it at the top level as specified in the official documentation.

Implementation Patterns with the Python SDK

Install the Python SDK with pip install anthropic and you can get started in just a few lines.

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)

To enable streaming, simply add stream=True to switch to chunk-based responses. Async processing is supported via the AsyncAnthropic client.

In production, always catch these two exception types and implement exponential backoff:

1. anthropic.RateLimitError (429) — Rate limit reached. Wait a few seconds and retry.
2. anthropic.BadRequestError (400) — Input token limit exceeded or malformed request format.

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 Configuration

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);

Install with npm install @anthropic-ai/sdk for Node.js 18+. Since the parameter design mirrors the Python SDK, if you know one, switching to the other has virtually zero learning curve.

It also works on Edge Runtimes like Cloudflare Workers and Vercel Edge, but streaming API behavior varies by runtime — it's recommended to first validate in a standard Node.js environment.

Extending Tool Integration with MCP

MCP (Model Context Protocol) is the standard interface for Claude to call external tools. Released by Anthropic as an open protocol in 2024, it lets you declaratively define access to databases, APIs, and file systems.

The basic flow for tool integration with MCP is as follows:

1. Implement an MCP server or adopt a community-provided server (Supabase, GitHub, Slack, etc.)
2. Pass tool definitions (name, description, JSON Schema) in the tools parameter of the request
3. When Claude returns a tool_use block, execute the tool on the server side
4. Add the result as tool_result to messages and resend to Claude
5. Repeat the loop until Claude returns a final answer

This pattern lets you build pipelines where Claude autonomously orchestrates multi-step processes like "user question → database search → answer generation based on results."

Example tool definition (weather retrieval):

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

Autonomous Processing Pipelines with Tool Calls

Anthropic Academy's "Build with Claude" provides a systematic guide to building autonomous processing workflows that go beyond single-message interactions.

Combining the Messages API with MCP tools lets you handle complex tasks that can't be completed with a single prompt. Here are some concrete configurations:

• Research assistance: "Research competitors and create a summary table" → Web search → Information gathering → Table generation
• Code generation + testing: "Implement this specification" → Code generation → Test execution → Error correction
• Data analysis: "Analyze sales data" → DB query → Aggregation → Chart data generation

The key is clearly defining the granularity of each task. A well-defined tool that specifies "what to use and what to return" yields more accurate output from Claude than an ambiguous goal.

Model Selection: When to Use Haiku, Sonnet, and Opus

Claude offers three model tiers suited for different use cases.

The standard approach in app development is to build the initial version with Sonnet, then switch high-frequency endpoints to Haiku during a cost optimization phase. Rather than using Opus for all requests, limiting it to tasks where accuracy is especially critical improves cost-effectiveness.

Specifying the model ID with a version (e.g., claude-sonnet-4-6 for the latest Sonnet) prevents unexpected behavior changes.

Cost Reduction Strategies Before Going to Production

Here are three cost-saving measures that deliver significant impact when implemented before moving to production.

Prompt Caching (up to 90% reduction)
For long system prompts or reference documents that are passed repeatedly, adding cache_control to enable cache hits can reduce input costs by up to 90%. For use cases that send the same system prompt thousands of times per day, the return on investment is extremely high.

Batch API (50% reduction)
For processing that doesn't require immediate responses (overnight batches, periodic reports, etc.), running it through the Message Batches API costs 50% of the standard rate. Results are retrieved asynchronously.

Offloading to Haiku
Simply routing low-complexity tasks like classification, labeling, and basic summarization to Haiku can reduce costs to 1/20th or less compared to Sonnet. Setting up a routing layer that assigns different models per task type is the standard configuration for production.

Pre-Production Checklist

Verify these 7 points before going to production:

1. Manage API keys via environment variables like .env — confirm they are not hardcoded in source code or repositories
2. Set max_tokens appropriately to prevent 400 errors from exceeding the limit
3. Implement retry logic with exponential backoff (for 429 / 529 errors)
4. Enable prompt caching to reduce the cost of repeated system prompts
5. Design routing to offload high-frequency, low-complexity processing to Haiku or the Batches API
6. Monitor rate limits (RPM / TPM) and implement distribution strategies to handle sudden request spikes
7. Apply masking to prevent API keys or personal information from appearing in logs

Implementing these in advance significantly reduces the risk of failures caused by traffic spikes or unexpected inputs. The official Building with Claude documentation is continuously updated with detailed API references and implementation samples — review it before starting your implementation.