Claude Agent SDKで独自ツールを連携する

Custom Toolsは、Agent SDKのエージェントから呼べる自分の関数です。Pythonの @tool、TypeScriptの tool() で名前・説明・入力スキーマ・ハンドラーを定義し、in-process MCP serverへ登録して query() に渡します。 Custom Tools公式

最小の設計

本文の例で、定義・登録・許可の対応を追います。

1. 1関数を定義count_lines：入力スキーマと処理結果を定める。
2. 2サーバーへ登録text-tools のツール一覧に加える。
3. 3queryで使うmcp__text-tools__count_lines を許可する。
4. 4結果を確認入力の数え方、空文字、例外と再実行を試す。

名前の対応に加え、使えるツール一覧と自動許可の範囲を別々に確認します。

最初は副作用のない「文字列の文字数を返す」などにします。入力スキーマで型を検証し、ハンドラーは必須の content 配列を返します。機械処理用の値は structuredContent、失敗を知らせる場合は isError を使う公式形式に合わせます。

文字列を受け取り、文字数と改行数を返すCustom Toolを作って。
外部通信とファイル変更はしない。入力上限、空文字、例外時の結果、テストを含めて。

ツールをClaudeへ登録すると、完全修飾名を mcp__サーバー名__ツール名 として許可リストへ追加できます。読み取り専用で副作用がないツールには readOnlyHint を付ける設計が可能です。 公式ガイド

TypeScriptで登録する最小例

TypeScript版の準備を済ませたフォルダーで、次をtool.tsとして保存します。公式例の構成に沿い、入力を検証して結果を返すツールを定義します。この例は改行区切りの要素数を数えるため、空文字も1行、末尾に改行があれば最後の空の要素も1行と数えます。実用時には必要な数え方へ揃えてください。

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

const countLines = tool(
  "count_lines",
  "Count lines in supplied text; does not read or change files",
  { text: z.string().describe("Text to count") },
  async ({ text }) => ({
    content: [{ type: "text", text: String(text.split(/\r?\n/).length) }],
    structuredContent: { lines: text.split(/\r?\n/).length }
  }),
  { annotations: { readOnlyHint: true } }
);

const localServer = createSdkMcpServer({
  name: "text-tools",
  version: "1.0.0",
  tools: [countLines]
});

for await (const message of query({
  prompt: "count_linesで、この文の行数を調べて。ファイルは読まないで。",
  options: {
    tools: [],
    mcpServers: { "text-tools": localServer },
    allowedTools: ["mcp__text-tools__count_lines"]
  }
})) {
  if (message.type === "result") console.log(message.subtype);
}

npm install zodを追加し、npx tsx tool.tsで実行します。ツール名、スキーマ、登録名、許可名の対応が一箇所でも違うと呼び出せません。まず副作用のない入力で試し、次にエラー時の isError とログを確認します。 コード例の tools: [] は組み込みツールをClaudeのコンテキストから外し、独自MCPだけを使わせる指定です。allowedToolsだけでは組み込みツールの可用性は制限されないため、可用性（tools）と許可（allowedTools）を別々に点検します。

実用化の境界

ファイル検査、社内API、記事台帳などへ広げると、認証、タイムアウト、レート制限、入力サイズ、監査ログ、権限分離が必要になります。ツール説明は「いつ使うか」と「使わない条件」まで書きます。ファイル削除や公開操作は別ツールに分け、明示承認を要求します。MCPの外部サーバーを使う場合は、Custom Toolとの責務と接続先を分けます。

Structured OutputはJSON形式、SDKの基礎は用語解説、Python/TypeScriptの導入はPython版・TypeScript版へ進めます。

限界

ツールが正しく呼ばれても、返すデータの意味や権限が正しいとは限りません。テスト用データで正常系・不正入力・例外・再実行を確認し、秘密情報をプロンプトやログへ出さないでください。

ツールの説明には、読み取りだけか、作成・更新・削除を伴うかを明記します。書き込みツールには対象ID、変更内容、確認フラグ、冪等性キーを求め、同じ依頼の再実行で重複しないようにします。外部APIの応答はそのまま信用せず、ステータス、スキーマ、権限、レート制限をアプリ側で確認します。試作から本番へ移すときは、許可リストと監査ログを再点検します。