Give Claude custom tools

概要

SDK の in-process MCP サーバーで自前の関数をツールとして定義し、Claude に呼ばせる仕組み。データベース、外部 API、ドメイン固有のロジックを渡せる。

仕様

やりたいことと手段

やりたいこと	手段
ツールを定義する	`@tool`（Python）/ `tool()`（TypeScript）に name・description・schema・handler を渡す
Claude に登録する	`create_sdk_mcp_server` / `createSdkMcpServer` で包み、`query()` の `mcpServers` に渡す
事前承認する	allowed tools に加える
組み込みツールを Claude のコンテキストから外す	残したい組み込みだけを列挙した `tools` 配列を渡す
並列で呼ばせる	副作用の無いツールに `readOnlyHint: true` を設定する
Claude が読むエラーメッセージを制御する	結果に `isError: true` を返し、生の例外を出す代わりに文面を組む
画像やファイルを返す	content 配列で `image` / `resource` ブロックを使う
機械可読な結果を返す	結果に `structuredContent` を設定する
ツールが多いとき	tool search で必要時に読み込む

ツールの 4 要素

要素	内容
Name	Claude が呼ぶときの一意な識別子
Description	何をするツールか。Claude はこれを読んでいつ呼ぶかを決める
Input schema	TypeScript は常に Zod スキーマ。handler の `args` はそこから自動で型付けされる。Python は `{"latitude": float}` のような dict で、SDK が JSON Schema に変換する。enum・範囲・任意フィールド・入れ子が要るときは、Python の decorator は完全な JSON Schema の dict も直接受け付ける
Handler	Claude がツールを呼んだときに走る async 関数

handler の戻り値

キー	必須	内容
`content`	必須	結果ブロックの配列。各ブロックの `type` は `"text"` / `"image"` / `"audio"` / `"resource"` / `"resource_link"`
`structuredContent`	任意	機械可読なデータとしての結果。`content` と併せて返る
`isError`	任意	`true` でツールの失敗を伝え、Claude が反応できるようにする

サーバーの動く場所

createSdkMcpServer / create_sdk_mcp_server で包んだサーバーは、別プロセスではなくアプリケーション内（in-process）で動く

TypeScript でのフィールド説明

Zod の .describe() を付けると、Claude が見るフィールドの説明になる

設定

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_temperature",
    "Get the current temperature at a location",
    {"latitude": float, "longitude": float},
)
async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:
    ...
    return {"content": [{"type": "text", "text": f"Temperature: {temp}°F"}]}

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_temperature],
)

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude coordinate"),
    longitude: z.number().describe("Longitude coordinate"),
  },
  async (args) => ({
    content: [{ type: "text", text: `Temperature: ${temp}°F` }],
  }),
);

制約・注意点

readOnlyHint: true は副作用の無いツールにのみ設定する。 並列実行の可否がこれで決まる
Description は Claude が呼ぶかどうかの判断材料になるため、内容が曖昧だと呼ばれない・誤って呼ばれる