MCPサーバーに関して⑥:Tools実装の実践
前回(⑤)は、Pythonの公式SDKでSQLiteデータベースを参照する2つのツール(get_schema と run_query)を持つ最小サーバーを作りました。今回はその続きとして、Toolsの実装を深掘りします。スキーマ定義、引数のバリデーション、エラー処理、戻り値の設計——実際に手を動かすとつまずきやすいポイントを、⑤のDBツール2つを題材に整理します。
この記事で分かること
- ツール定義の必須の3点(名前・説明文・スキーマ)と、Pythonでは何がそれぞれに対応するか
- 引数の必須・任意の表し方と、制約(長さ・範囲・列挙)をスキーマに載せる方法
- 引数チェックの2段構えと、
isErrorを使ったエラー返却 - 戻り値の設計:テキスト中心の
contentと構造化出力の使い分け - LLMに選ばれやすいツール名・説明文の書き方と、
annotationsの付け方
ツール定義の必須の3点は「名前・説明文・スキーマ」
仕様上、ツール定義の必須の3点は**名前(name)・説明文(description)・入力スキーマ(inputSchema)**です。クライアントは tools/list でこの一覧を取得し、モデルがどれを呼ぶか選びます。呼び出しは tools/call で、結果は content と isError で返ります。
Python SDKでは、この3点はコードの3か所からそのまま作られます(⑤で見た通りです)。
| 項目 | 役割 | 誰が読むか | Pythonでの出どころ |
|---|---|---|---|
name |
ツールの一意な識別子 | クライアント・モデル | 関数名 |
description |
何をするツールかの説明 | 主にモデル | 関数のdocstring |
inputSchema |
引数の型・必須条件(JSON Schema) | モデルとSDKの検証 | 引数の型ヒント(+ Field) |
from mcp.server import MCPServer
mcp = MCPServer("sqlite-readonly-server")
@mcp.tool()
def get_schema() -> str:
"""サンプルDBのテーブル一覧と、各テーブルのカラム名・型を返す。
クエリを書く前に、まずこのツールでDBの構造を確認すること。
"""
...
get_schema という関数名がそのままツール名に、docstringが説明文に、引数の型ヒントが入力スキーマになります。get_schema は引数がないので、書くべき型ヒントもありません(スキーマの引数部分は空になります)。
仕様ではツール名は1〜128文字、英数字・_・-・. のみが推奨され、スペースやカンマは避けることになっています。Pythonでは関数名のスネークケース(get_schema、run_query のような形)がそのままこの推奨に収まります。
引数の設計:必須・任意と、制約の伝え方
Python SDKでは、デフォルト値のない引数が必須、デフォルト値のある引数が任意になります。Pythonの関数定義そのままの感覚です。
制約や引数ごとの説明を足したいときは、型を Annotated で包んでPydanticの Field を付けます。⑤の run_query に「取得行数の上限を引数化する」改良を加えると、こうなります。
from typing import Annotated
from pydantic import Field
from mcp.server import MCPServer
mcp = MCPServer("sqlite-readonly-server")
@mcp.tool()
def run_query(
sql: Annotated[
str,
Field(
min_length=1,
max_length=4000,
description="実行するSELECT文(1文だけ)。テーブル名やカラム名が分からない場合は、先にget_schemaで確認すること",
),
],
max_rows: Annotated[
int, Field(ge=1, le=100, description="取得する最大行数")
] = 100,
) -> str:
"""読み取り専用のSELECTクエリを実行し、結果をテキストで返す。"""
...
この定義から、SDKは次のような入力スキーマを生成します。
{
"type": "object",
"properties": {
"sql": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"description": "実行するSELECT文(1文だけ)。テーブル名やカラム名が分からない場合は、先にget_schemaで確認すること"
},
"max_rows": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 100,
"description": "取得する最大行数"
}
},
"required": ["sql"]
}
ポイントは3つです。
-
必須と任意はデフォルト値で表す。
sqlはデフォルト値がないのでrequiredに入り、max_rowsはデフォルト値100があるので任意になります。曖昧なままにすると、モデルが「要るのか要らないのか」迷います。 -
制約は
Fieldでスキーマに載せる。 文字列の長さはmin_length/max_length、数値の範囲はge(以上)/le(以下)で書きます。候補を列挙したい場合は、型ヒントをLiteral["asc", "desc"]のようにするとスキーマではenumになります。 -
引数ごとの説明は
Field(description=...)に書く。 これがJSON Schemaのdescriptionになり、モデルが引数を決める手がかりになります。
大事なのは、制約はスキーマに載せて初めて「検証」になることです。docstringに「最大100行まで」と書くのはモデルへのお願いにすぎませんが、Field(le=100) なら、101以上が渡ってきた時点でSDKが関数の実行前に弾きます(次の節の「1段目」です)。
バリデーションは2段構えにする
引数チェックはスキーマによる検証とハンドラ内の業務チェックの2段で考えます。
- スキーマ検証(1段目):型・長さ・範囲・必須漏れなど、形の問題はここで止まります。Python SDKでは、検証に失敗した呼び出しは関数が実行されず、「上限を超えた」といった内容のエラーがツール結果としてモデルに返ります。モデルはそれを読んで、値を直して再試行できます。
-
業務チェック(2段目):型は正しいが意味的に使えない値のチェックです。
run_queryのSQLは「文字列」という形だけでは中身を縛れないため、⑤で実装した「SELECT文だけ通す」「単文のみ」「行数上限」という検証がこの段にあたります。⑤の多層防御のうち、層2〜4(文の検証・単文制限・行数上限)が業務チェック、層1(読み取り専用接続)は実行環境側の制約でした。
つまり、スキーマで表せる制約はスキーマへ、表せない意味の制約はハンドラへ、が役割分担です。
エラーは2種類に分ける
仕様はエラーを2種類に分けています。これを混同すると、モデルが自己修正できなくなります。
| 種類 | 例 | 返し方 |
|---|---|---|
| プロトコルエラー | 存在しないツール名、壊れたリクエスト | JSON-RPCエラー |
| ツール実行エラー | SQLの文法違い、範囲外の値、DBの失敗 |
isError: true の通常結果 |
ツール実行エラーは普通の結果として isError: true と説明文を返すのが決まりです。モデルは内容を読んで引数を直し、再試行できます。Python SDKでは、ツール関数の中で起きた例外は原則としてツール実行エラーに変換されます。ただし MCPError(from mcp import MCPError)を投げた場合だけは例外で、ラッパーに捕捉されず、プロトコルエラー(JSON-RPCエラー)としてクライアントに返ります。一方、ResourcesやPromptsのコールバックには isError の受け皿がないため、そちらで投げた例外はプロトコルエラーになります。
Pythonでのエラーの返し方は4通り
Python SDKで、ツールの中から失敗を伝える方法は次の4通りです。
1. エラー文字列を返す(⑤の run_query の方式)
@mcp.tool()
def run_query(sql: str) -> str:
"""読み取り専用のSELECTクエリを1文だけ実行し、結果をテキストで返す。"""
statement = sql.strip().rstrip(";").strip()
if not statement:
return "エラー: SQLが空です。"
...
通常の戻り値として返すだけなので実装は簡単で、モデルは文字列を読んでSQLを直せます。ただし結果に isError は付かないため、呼び出し側のプログラムからは成功と失敗を区別できません。
2. ToolError を投げる
予期できる失敗には、公式ドキュメントで案内されている ToolError を使うのが基本です。
import re
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("sqlite-readonly-server")
@mcp.tool()
def run_query(sql: str) -> str:
"""読み取り専用のSELECTクエリを1文だけ実行し、結果をテキストで返す。"""
statement = sql.strip().rstrip(";").strip()
if not statement:
raise ToolError("SQLが空です。SELECT文を1文指定してください。")
if ";" in statement:
raise ToolError(
"実行できるのは1文だけです。文を分けず、1文だけ渡してください。"
)
if not re.match(r"(?is)^(select|with)\b", statement):
raise ToolError(
"SELECT文(またはWITHで始まるSELECT)だけ実行できます。"
f"受け取った文の先頭: {statement[:20]!r}"
)
...
ToolError のメッセージは isError: true の結果としてクライアントに届き、モデルが読める形で content に入ります。「失敗した」という事実と理由の両方を伝えられるのが、文字列返しとの違いです。
3. 予期しない例外(そのまま投げっぱなし)
想定外の例外もSDKが捕捉し、isError: true の結果に変換するため、サーバーが落ちることはありません。ただしこの場合、例外のメッセージはクライアントに届かず、結果は「Error executing tool run_query」のような名前だけの文面になります。詳しい原因はサーバー側のログにしか残りません。
4. MCPError を投げる(プロトコルエラーとして返す)
MCPError(from mcp import MCPError)は、ツール関数のラッパーが捕捉しない唯一の例外です。投げると結果そのものが返らず、tools/call のリクエスト自体がJSON-RPCエラーで失敗します。モデルには何も届かず、エラーはホストアプリケーション側に返ります(code・message・data はそのまま届きます)。
使うのは「モデルが引数を直しても解決しない」失敗のときです。例えば、参照先のDBファイルが存在しないのはサーバー側のセットアップ不備で、モデルがSQLを書き直して再試行しても無駄です。
from mcp import MCPError
from mcp.types import INTERNAL_ERROR
if not DB_PATH.exists():
raise MCPError(
code=INTERNAL_ERROR,
message="参照先のDBファイルが見つかりません。サーバー側のセットアップを確認してください。",
)
判断の目安は「もっと賢いモデルなら、この失敗を避けられたか」です。避けられたなら ToolError、避けられないなら MCPError と考えます。
この4つを踏まえた使い分けは次の通りです。
-
予期できる失敗は
ToolErrorで投げる。 メッセージには「何が悪くて、どう直せばいいか」を具体的に書きます。 -
文字列返しは、モデルにだけ読ませれば十分な最小構成向け。 ⑤のように学習用のサンプルでは悪くありませんが、実務では成否を区別できる
ToolErrorの方が扱いやすくなります。 -
リクエスト自体の不備は
MCPErrorでプロトコルエラーにする。 前提条件の欠落やサーバー側のセットアップ不備など、モデルに直させても無駄な失敗は、モデルではなくホスト側に返します。 - どちらでも、メッセージの書き方が肝心です。
# 悪い例:何が悪いか分からない
raise ToolError("エラー")
# 良い例:受け取った値と直し方が分かる
raise ToolError("SELECT文だけ実行できます。受け取った文の先頭: 'DELETE'")
戻り値の設計:テキスト中心、構造化出力は任意
ツールの結果は content(テキスト・画像・音声などのブロック配列)が中心です。仕様上、構造化出力は任意で、使う場合は outputSchema を宣言し、結果を structuredContent で返します。後方互換のため、構造化出力と一緒にJSONをテキストブロックにも入れることが推奨されています。
Python SDKでは、この宣言を手で書く必要はありません。戻り値の型ヒントがそのまま outputSchema になります。
-
-> strで文字列を返すと、contentにテキストが入り、structuredContentには{"result": "..."}という形で同じ文字列が入ります。モデルが読むのはcontentの方です。run_queryの結果(ヘッダー行+データ行のテキスト)はこの形で十分です。 - Pydanticの
BaseModel(やTypedDict、dataclass)を返すと、そのクラス定義がoutputSchemaになり、structuredContentにオブジェクトそのものが入ります。contentには同じオブジェクトをJSONテキストにしたものが自動で入るため、モデルも読めます。
get_schema を構造化して返す形に変えると、こうなります。
from pydantic import BaseModel, Field
from mcp.server import MCPServer
mcp = MCPServer("sqlite-readonly-server")
class ColumnInfo(BaseModel):
"""テーブルのカラム1件分の情報。"""
name: str = Field(description="カラム名")
type: str = Field(description="SQLiteの型名(INTEGER、TEXTなど)")
primary_key: bool = Field(description="主キーの一部ならtrue")
class TableInfo(BaseModel):
"""テーブル1件分の情報。"""
name: str = Field(description="テーブル名")
columns: list[ColumnInfo]
class DatabaseSchema(BaseModel):
"""DB全体のスキーマ情報。"""
tables: list[TableInfo]
@mcp.tool()
def get_schema() -> DatabaseSchema:
"""サンプルDBのテーブル一覧と、各テーブルのカラム名・型を構造化して返す。"""
conn = _connect_readonly() # ⑤で定義した読み取り専用接続のヘルパー
try:
tables: list[TableInfo] = []
for (table,) in conn.execute(
"SELECT name FROM sqlite_master "
"WHERE type = 'table' AND name NOT LIKE 'sqlite_%' "
"ORDER BY name"
):
columns = [
ColumnInfo(
name=info[1], type=info[2], primary_key=bool(info[5])
)
for info in conn.execute(f"PRAGMA table_info({table})")
]
tables.append(TableInfo(name=table, columns=columns))
return DatabaseSchema(tables=tables)
finally:
conn.close()
戻した値は outputSchema で検証されてからクライアントに届きます。スキーマに合わない値を返すと、その呼び出し自体がツールエラーになります。
設計の目安は次のとおりです。
-
モデルに読ませる結果はテキストで十分です。まずは
-> strの1本で始めましょう。 -
プログラムで後処理する結果(スキーマ情報、件数、ID、状態など)は、モデルクラスを返すと
structuredContentで受け取れます。 - 構造化出力が要らないツールは
@mcp.tool(structured_output=False)でテキストだけにできます。 - 返すクラスには型ヒントを必ず付けること。注釈のないクラスを返すとスキーマを作れず、オブジェクトの
repr(<... object at 0x...>のような文字列)がモデルに届く事故になります。
名前と説明文は「LLMへの説明書」
モデルはツール一覧の description を主に見て、どのツールを呼ぶか決めます(name や inputSchema も判断材料になります)。つまり説明文=docstringは人間向けのドキュメントではなく、モデルへの指示文です。
- 動詞から始めて、何をするか・何が返るかを1〜2文で書く。 例:「サンプルDBのテーブル一覧と、各テーブルのカラム名・型を返す」
-
似たツールの違いを書き分ける。
get_schemaとrun_queryが両方あるなら、「カラム名が分からない場合は、先にget_schemaで確認すること」のように、使い分けの条件を互いのdocstringに入れます(⑤で実践した形です)。 - 制約も説明に含める。 「使えるのはSELECT文のみ」「最大100行まで」まで書いておくと、モデルが無効な呼び出しをする確率が下がります。ただし検証そのものはスキーマと業務チェックの仕事で、説明は補助だという役割分担は崩さないこと。
-
ツール名は動詞+対象の形にする。
get_schema、run_queryのように、読んだだけで動作が想像できる名前にします。
annotationsでクライアントに性質を伝える
ツールの性質(読み取り専用か、破壊的かなど)は annotations でクライアントに伝えられます。Python SDKでは、デコレータに ToolAnnotations を渡します。あわせて title でUI表示用の名前も付けられます。
from mcp.server import MCPServer
from mcp.types import ToolAnnotations
mcp = MCPServer("sqlite-readonly-server")
@mcp.tool(
title="DBスキーマ取得",
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
)
def get_schema() -> str:
"""サンプルDBのテーブル一覧と、各テーブルのカラム名・型を返す。"""
...
ヒントは4種類あります。
| ヒント | 意味 |
|---|---|
read_only_hint |
環境を変更しない(読み取り専用) |
destructive_hint |
破壊的な更新を行いうる(書き込み系のツール向け) |
idempotent_hint |
同じ引数で繰り返し呼んでも追加の効果がない |
open_world_hint |
Webなど開かれた外部とやり取りする |
get_schema と run_query はどちらも読み取り専用で、対象もローカルのDBだけなので、read_only_hint=True、open_world_hint=False が実態に合います。クライアントはこれを見て「実行前にユーザーの確認を求めるか」などの判断材料にします。
ただし、annotationsはヒントであって保証ではありません。読み取り専用の担保は、あくまで⑤で実装した読み取り専用接続や文の検証といった実装側の仕組みです。annotationsは実態に正直に付け、過信しないことが大切です。
よくある失敗例
| 失敗 | どうなるか | 対策 |
|---|---|---|
| docstringが「便利なツール」だけ | モデルがいつ使うか判断できない | 何をするか・何が返るかを具体的に書く |
| 任意にしたい引数にデフォルト値を付け忘れる | 必須扱いになり、モデルが値をでっち上げて渡す | デフォルト値で任意を明示する |
| 制約をdocstringにしか書かない | 検証されず、そのまま関数に渡ってしまう |
Field や Literal でスキーマに載せる |
| 予期できる失敗を素の例外で投げる |
isError にはなるがメッセージが届かず、直し方を伝えられない |
ToolError で理由と直し方を書いて投げる |
| 型ヒントのないクラスを返す | スキーマが作れず、repr の文字列がモデルに届く |
BaseModel や TypedDict で型を注釈して返す |
| ツール名にスペースや日本語を使う | 仕様の推奨から外れ、互換性が落ちる | 英数字・_・-・. だけにする |
まとめ
- ツール定義の必須の3点は名前・説明文・スキーマ。Pythonでは関数名・docstring・型ヒントがそれぞれに対応し、説明文はモデルへの指示文として書く。
- 必須・任意はデフォルト値で表し、制約と引数の説明は
FieldやLiteralでスキーマに集約する。 - バリデーションはスキーマ検証+ハンドラ内の業務チェックの2段構え。スキーマで表せない意味の制約(SQLの文種別など)は業務チェックで見る。
- 実行時の失敗は
isError: trueの通常結果で返す。予期できる失敗はToolErrorで直し方まで書くのが基本で、モデルに直させても無駄なリクエスト自体の不備はMCPErrorでプロトコルエラーとして返す。 - 戻り値はテキスト中心。構造化出力は戻り値の型ヒントから自動で作られ、必要なときだけモデルクラスを返す。
-
annotationsはクライアントへのヒント。正直に付けるが、担保は実装側の仕組みで取る。
次回はResourcesとPromptsの実装を取り上げ、Toolsとの組み合わせ方を解説します。
関連記事
参考リンク
- Tools - Model Context Protocol(仕様 2026-07-28)
- Tools - MCP Python SDK
- Structured Output - MCP Python SDK
- Troubleshooting - MCP Python SDK
- modelcontextprotocol/python-sdk - GitHub
用語集
- JSON Schema:JSONデータの形(型・必須項目・値の範囲など)を宣言する仕様。MCPではツールの入力・出力の形を表すのに使う。
- inputSchema:ツールが受け取る引数の形を定義したJSON Schema。モデルはこれを見て引数を作る。Python SDKでは型ヒントから自動生成される。
- outputSchema:ツールが返す構造化データの形を定義したJSON Schema。Python SDKでは戻り値の型ヒントから自動生成される。
-
structuredContent:
outputSchemaに沿った機械可読な結果。テキストのcontentと併用する。 -
isError:ツールの実行結果が失敗であることを示すフラグ。
trueならツール側の失敗で、モデルは内容を読んで再試行できる。 - Pydantic:Pythonでデータの形(スキーマ)を宣言し、検証するためのライブラリ。MCPのPython SDKは、型ヒントからのスキーマ生成や引数・戻り値の検証に使っている。
-
Field:Pydanticで、引数やフィールドに説明や制約(長さ・範囲など)を付ける仕組み。
Annotated[型, Field(...)]の形で書く。 -
ToolError:Python SDKで、ツールの失敗をモデルに伝えるときに投げる例外。
isError: trueの結果に変換され、メッセージがモデルに届く。 -
MCPError:Python SDKのプロトコルエラーを表す例外(
from mcp import MCPError)。ツール関数の中で投げるとラッパーに捕捉されず、JSON-RPCエラーとしてクライアントに返る。モデルでは直せない、リクエスト自体の不備に使う。 - annotations:ツールの性質(読み取り専用か、破壊的かなど)をクライアントに伝える任意のヒント。実行内容は変えず、保証にもならない。
- JSON-RPC 2.0:JSONでリクエストとレスポンスをやり取りする遠隔呼び出しの仕組み。MCPのメッセージ交換の土台。