本文へ移動
Senu English

操作を MCP ツールとして公開する

約 4 分で読めます

操作は、mcp::tool で一覧に載せると MCP ツールになります。AI アシスタントは、JSON API やページと同じ関数を、同じ権限検査の後ろで呼び出します。

MCP とは何で、なぜ同じ関数から提供するのですか

MCP (Model Context Protocol) は、Claude のような AI アシスタントが他のプログラムのツールを呼ぶための取り決めです。ツールは名前、説明、引数の JSON Schema を持ちます。ツールを API とは別の実装として書くと、2 つはずれていきます。片方だけ検証が違ったり、テナントの検査を忘れたりします。Senu ではツールと API ルートが同じ Operation なので、食い違うことがありません。契約テストが 2 つの答えを比べます。

ツールはどう一覧にしますか

pub fn tools() -> Vec<McpTool<Inventory>> {
    vec![mcp::tool(&GET_STOCK), mcp::tool(&LIST_LOW_STOCK)]
}

各ツールの名前と説明は操作から取ります。入力スキーマは宣言したパラメータから作ります。プロパティはどれも説明つきの文字列で、required には必須のものが並び、additionalProperties は false です。操作は読み取り専用なので、どのツールにも readOnlyHint: true が付きます。自動で公開されるものはなく、マクロもリフレクションも使いません。

サーバーはどう動かしますか

async fn serve_mcp() -> Result<(), String> {
    // Stdio trusts the local process that starts the server, so every call
    // is bound to one principal chosen here.
    McpServer::with_tools(Inventory::sample(), NORTH_CLERK, tools())
        .map_err(|err| err.to_string())?
        .with_info("inventory", "1.0.0")
        .serve_stdio()
        .await
        .map_err(|err| err.to_string())
}

serve_stdio は、クライアントが stdin を閉じるまで、プロセスの stdin と stdout で MCP を話します。その間、stdout には JSON-RPC だけが流れるので、ログは stderr に書きます。with_info は、initialize が報告する名前とバージョンを決めます。

すべての呼び出しは、あなたが渡した 1 つのプリンシパルとして走ります。MCP の仕様では、stdio サーバーは資格情報を環境から受け取ります。サーバーは自分を起動したローカルのプロセスを信頼し、遠隔の相手を認証しません。このプリンシパルは慎重に選び、アシスタントに持たせてよい権限だけを与えてください。

アシスタントはどうつなぎますか

多くの MCP クライアントは、起動するコマンドを書いた JSON ファイルを読みます。上の例なら次のとおりです。

{
  "mcpServers": {
    "inventory": {
      "command": "/absolute/path/to/inventory",
      "args": ["mcp"]
    }
  }
}

クライアントはプログラムを起動し、initialize を送り、ツールを一覧し、呼び出します。呼び出しとその答えは、通信上では次のようになります。

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_low_stock","arguments":{"below":"4"}}}
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"below\":4,\"items\":[{\"name\":\"Nut M8\",\"sku\":\"NUT-8\",\"units\":3},{\"name\":\"Washer M8\",\"sku\":\"WASHER-8\",\"units\":0}]}"}],"structuredContent":{"below":4,"items":[{"name":"Nut M8","sku":"NUT-8","units":3},{"name":"Washer M8","sku":"WASHER-8","units":0}]},"isError":false}}

結果は 2 通りで届きます。JSON を読むクライアントには structuredContent、読まないクライアントには同じ JSON を入れたテキストです。

エラーはどう見えますか

操作のエラーは、isError: true と {"error": "<code>"} を持つ通常のツール結果です。コードは JSON API と同じで、forbidden、invalid_request、not_found、internal、または操作独自のものです。アシスタントはこれを読んで、呼び出しを直せます。未知のツール名は JSON-RPC のエラー -32602 になります。メッセージは固定で、名前を繰り返しません。

MCP over HTTP は使えますか

バージョン 0.2 では使えません。ツールは stdio で動きます。ローカルのプログラムを起動するアシスタントに向いた形です。遠隔のアシスタントには JSON API を使わせるか、あとのバージョンの HTTP トランスポートを待ってください。遠隔の呼び出し元はリクエストごとに認証する必要があるので、専用の仕様が要ります。

アシスタントにとって良いツールとは

次のページ: デプロイと運用。