MCP server Anthropic API integration

SDK setup and authentication

npm install @anthropic-ai/sdk zod

import Anthropic from "@anthropic-ai/sdk";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxRetries: 2,   // retries on 529 overloaded and 5xx automatically
  timeout: 60_000, // ms — Claude can take 30-60s on long generations
});

const server = new McpServer({ name: "claude-tools", version: "1.0.0" });

The SDK is initialized once at module level and is safe to reuse across tool calls. The maxRetries default of 2 covers transient 529 and 5xx errors. For high-throughput tools, set maxRetries: 0 and implement your own backoff (see the error handling section below) so you can log retry attempts and respect per-minute token limits.

Model selection

The current Claude model family as of mid-2026:

Pass the model ID as a tool argument rather than hardcoding it. Expose a list_claude_models tool that returns the table above so the calling agent can select the right model for cost-vs-quality tradeoffs without needing to know model IDs out of band.

Messages API tool with prompt caching

The Anthropic Messages API structures content as typed blocks. The most important non-obvious rule: cache_control must be applied to the last user turn or system prompt block that you want to treat as a cache boundary. Applying it to a block in the middle of a long system prompt wastes tokens.

server.tool(
  "ask_claude",
  "Send a message to Claude and return the response. Uses prompt caching for repeated system prompts.",
  {
    model: z.enum(["claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5-20251001"])
      .default("claude-sonnet-4-6"),
    system_prompt: z.string().optional()
      .describe("System context — cached automatically if > 1024 tokens"),
    user_message: z.string(),
    max_tokens: z.number().int().min(1).max(8192).default(1024),
  },
  async ({ model, system_prompt, user_message, max_tokens }) => {
    try {
      const response = await anthropic.messages.create({
        model,
        max_tokens,
        // Apply cache_control to system prompt if present
        // Anthropic caches prompts > 1024 tokens when cache_control is set
        system: system_prompt
          ? [{ type: "text", text: system_prompt, cache_control: { type: "ephemeral" } }]
          : undefined,
        messages: [{ role: "user", content: user_message }],
      });

      const textBlock = response.content.find(b => b.type === "text");
      const replyText = textBlock?.type === "text" ? textBlock.text : "(no text response)";

      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            reply: replyText,
            model: response.model,
            stop_reason: response.stop_reason,
            usage: {
              input_tokens: response.usage.input_tokens,
              output_tokens: response.usage.output_tokens,
              cache_read_input_tokens: response.usage.cache_read_input_tokens ?? 0,
              cache_creation_input_tokens: response.usage.cache_creation_input_tokens ?? 0,
            },
          }),
        }],
      };
    } catch (err) {
      return anthropicErrorToToolResult(err);
    }
  }
);

Prompt caching is automatic when cache_control: { type: "ephemeral" } is present and the content block is ≥ 1024 tokens. Cache writes cost 25% more than regular input tokens; cache reads cost 10%. The break-even is the second identical request — every request after that is 90% cheaper for that prefix. Check usage.cache_read_input_tokens > 0 in the response to verify a hit occurred.

Token budget tracking

Claude's 200k-token context is generous but not unlimited. MCP tools that accumulate conversation history across calls can overflow silently — the API returns an error, but the caller just sees a failed tool call without context. Track token usage per call and check before the next call:

// Module-level token budget tracker
const tokenBudget = {
  inputTotal: 0,
  outputTotal: 0,
  cacheReads: 0,

  record(usage: Anthropic.Usage) {
    this.inputTotal += usage.input_tokens;
    this.outputTotal += usage.output_tokens;
    this.cacheReads += usage.cache_read_input_tokens ?? 0;
  },

  estimateNextCallFit(estimatedInputTokens: number, maxOutputTokens: number, modelLimit = 200_000): boolean {
    return estimatedInputTokens + maxOutputTokens <= modelLimit;
  },
};

server.tool(
  "get_token_usage",
  "Return the cumulative token usage for this MCP server session",
  {},
  async () => {
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          input_tokens_total: tokenBudget.inputTotal,
          output_tokens_total: tokenBudget.outputTotal,
          cache_reads_total: tokenBudget.cacheReads,
          estimated_cost_note: "Cache reads are ~90% cheaper than regular input tokens",
        }),
      }],
    };
  }
);

For the broader token budget management pattern across MCP tools, see token budget management for MCP servers.

Buffered streaming

The Anthropic SDK's streaming API uses an async iterator over MessageStreamEvents. MCP tool handlers return a complete result — they can't yield chunks mid-execution. Use stream.finalMessage() to buffer:

server.tool(
  "claude_long_generation",
  "Generate long-form content with Claude — buffers the full stream before returning",
  {
    prompt: z.string(),
    model: z.enum(["claude-opus-4-7", "claude-sonnet-4-6"]).default("claude-sonnet-4-6"),
    max_tokens: z.number().int().default(4096),
  },
  async ({ prompt, model, max_tokens }) => {
    try {
      const stream = anthropic.messages.stream({
        model,
        max_tokens,
        messages: [{ role: "user", content: prompt }],
      });

      // finalMessage() collects all stream events and returns the complete Message
      const message = await stream.finalMessage();

      const text = message.content
        .filter(b => b.type === "text")
        .map(b => b.type === "text" ? b.text : "")
        .join("");

      tokenBudget.record(message.usage);

      return {
        content: [{ type: "text", text }],
      };
    } catch (err) {
      return anthropicErrorToToolResult(err);
    }
  }
);

For more on the streaming-in-MCP pattern and when to use the two-tool start/poll approach instead, see streaming responses in MCP servers.

Nested tool use

Claude supports tool use — the model can respond with tool_use content blocks requesting a function call. When your MCP tool calls Claude with tools enabled, Claude may respond with tool use requests rather than text. You need to handle this loop:

server.tool(
  "claude_agent_loop",
  "Run a Claude agent loop that can call sub-tools (calculator, lookup) until it produces a final answer",
  {
    task: z.string(),
    max_rounds: z.number().int().min(1).max(8).default(5),
  },
  async ({ task, max_rounds }) => {
    const tools: Anthropic.Tool[] = [
      {
        name: "calculate",
        description: "Evaluate a mathematical expression",
        input_schema: {
          type: "object",
          properties: { expression: { type: "string", description: "Math expression to evaluate" } },
          required: ["expression"],
        },
      },
    ];

    const messages: Anthropic.MessageParam[] = [
      { role: "user", content: task },
    ];

    for (let round = 0; round < max_rounds; round++) {
      const response = await anthropic.messages.create({
        model: "claude-sonnet-4-6",
        max_tokens: 1024,
        tools,
        messages,
      });

      tokenBudget.record(response.usage);

      if (response.stop_reason === "end_turn") {
        const textBlock = response.content.find(b => b.type === "text");
        const text = textBlock?.type === "text" ? textBlock.text : "(no answer)";
        return { content: [{ type: "text", text }] };
      }

      if (response.stop_reason === "tool_use") {
        // Add Claude's response (with tool_use blocks) to messages
        messages.push({ role: "assistant", content: response.content });

        // Execute each tool call and collect results
        const toolResults: Anthropic.ToolResultBlockParam[] = [];
        for (const block of response.content) {
          if (block.type !== "tool_use") continue;
          let result: string;
          if (block.name === "calculate") {
            try {
              // Safe eval replacement — parse and evaluate only numeric expressions
              result = String(Function('"use strict"; return (' + block.input.expression + ')')());
            } catch {
              result = "Error: invalid expression";
            }
          } else {
            result = "Tool not found";
          }
          toolResults.push({ type: "tool_result", tool_use_id: block.id, content: result });
        }

        messages.push({ role: "user", content: toolResults });
        continue;
      }

      // stop_reason === "max_tokens" or unexpected
      break;
    }

    return {
      isError: true,
      content: [{ type: "text", text: `Agent loop ended after ${max_rounds} rounds without a final answer` }],
    };
  }
);

The recursion risk: if your MCP server's own tools are exposed to Claude (as tools in the above loop), Claude might call your MCP tool, which calls Claude, which calls your MCP tool. Set a conservative max_rounds and track depth in module state to break cycles.

Error handling

function anthropicErrorToToolResult(err: unknown) {
  if (err instanceof Anthropic.APIError) {
    const retryable = err.status === 429 || err.status === 529 || err.status >= 500;
    return {
      isError: true,
      content: [{
        type: "text" as const,
        text: JSON.stringify({
          error: `Anthropic API error (${err.status})`,
          message: err.message,
          retryable,
          hint: err.status === 529
            ? "Claude is temporarily overloaded — retry in 5-30 seconds"
            : err.status === 429
            ? "Rate limit reached — check x-ratelimit-reset headers and retry"
            : undefined,
        }),
      }],
    };
  }
  throw err;
}

The overloaded_error (529) is specific to Anthropic and means the API received more traffic than capacity can serve at that moment. Unlike a rate limit error (which means you sent too many requests), an overloaded error means Anthropic is at capacity. Back off 5–30 seconds and retry. For MCP tools where the caller can't wait, return isError: true with the retry hint and let the calling agent decide when to retry.

For the general error handling pattern in MCP tools, see error handling patterns for MCP tools.

Frequently asked questions

Further reading

• MCP tools for the OpenAI API — chat completions, function calling, rate limits
• MCP tools for Ollama — local LLM inference, model management, health checks
• MCP tools for AWS Bedrock — Converse API, IAM auth, cross-region inference
• Token budget management for MCP servers
• Streaming responses in MCP servers
• Caching patterns for MCP tool responses
• Error handling patterns for MCP tools
• AliveMCP — production protocol monitoring for MCP servers