このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring AI 1.1.7 を使用してください！

MCP アノテーションの特殊パラメーター

MCP アノテーションは、アノテーションされたメソッドに追加のコンテキストと機能を提供するいくつかの特殊なパラメーター型をサポートしています。これらのパラメーターはフレームワークによって自動的に挿入され、JSON スキーマ生成からは除外されます。

特殊なパラメーター型

MetaProvider

MetaProvider インターフェースは、ツール、プロンプト、リソース宣言内の _meta フィールドのデータを提供します。

概要

@McpTool(metaProvider = …)、@McpPrompt(metaProvider = …)、@McpResource(metaProvider = …) で参照されるクラスとして実装されています。
起動時にツール / プロンプト / リソース仕様に静的メタデータまたは計算メタデータを添付できるようにする
デフォルトの DefaultMetaProvider は空のマップを返します (no _meta appended)

カスタム MetaProvider

public class MyToolMetaProvider implements MetaProvider {

    @Override
    public Map<String, Object> getMeta() {
        return Map.of(
            "version", "1.0",
            "team", "platform",
            "experimental", false
        );
    }
}

@McpTool(name = "my-tool",
         description = "Tool with metadata",
         metaProvider = MyToolMetaProvider.class)
public String myTool(@McpToolParam(description = "Input") String input) {
    return "Processed: " + input;
}

@McpPrompt と @McpResource にも同じパターンが当てはまります。

McpMeta

McpMeta クラスは、MCP リクエスト、通知、結果からのメタデータへのアクセスを提供します。

概要

メソッドパラメーターとして使用された場合、自動的に挿入されます
パラメーター数の制限と JSON スキーマ生成から除外
get(String key) メソッドを通じてメタデータへの便利なアクセスを提供します
リクエストにメタデータが存在しない場合は、空の McpMeta オブジェクトが挿入されます。

ツールでの使用

@McpTool(name = "contextual-tool", description = "Tool with metadata access")
public String processWithContext(
        @McpToolParam(description = "Input data", required = true) String data,
        McpMeta meta) {

    // Access metadata from the request
    String userId = (String) meta.get("userId");
    String sessionId = (String) meta.get("sessionId");
    String userRole = (String) meta.get("userRole");

    // Use metadata to customize behavior
    if ("admin".equals(userRole)) {
        return processAsAdmin(data, userId);
    } else {
        return processAsUser(data, userId);
    }
}

リソースでの使用

@McpResource(uri = "secure-data://{id}", name = "Secure Data")
public ReadResourceResult getSecureData(String id, McpMeta meta) {

    String requestingUser = (String) meta.get("requestingUser");
    String accessLevel = (String) meta.get("accessLevel");

    // Check access permissions using metadata
    if (!"admin".equals(accessLevel)) {
        return ReadResourceResult.builder(List.of(
            new TextResourceContents("secure-data://" + id,
                "text/plain", "Access denied")
        )).build();
    }

    String data = loadSecureData(id);
    return ReadResourceResult.builder(List.of(
        new TextResourceContents("secure-data://" + id,
            "text/plain", data)
    )).build();
}

プロンプトでの使用

@McpPrompt(name = "localized-prompt", description = "Localized prompt generation")
public GetPromptResult localizedPrompt(
        @McpArg(name = "topic", required = true) String topic,
        McpMeta meta) {

    String language = (String) meta.get("language");
    String region = (String) meta.get("region");

    // Generate localized content based on metadata
    String message = generateLocalizedMessage(topic, language, region);

    return GetPromptResult.builder(List.of(new PromptMessage(Role.ASSISTANT, TextContent.builder(message).build())))
        .description("Localized Prompt")
        .build();
}

@McpProgressToken

@McpProgressToken アノテーションは、MCP リクエストから進行状況トークンを受信するためのパラメーターをマークします。

概要

パラメーター型は String である必要があります
リクエストから進行トークンの値を自動的に受信します
生成された JSON スキーマから除外
進捗トークンが存在しない場合は、null が注入される
長時間実行される操作を追跡するために使用されます

ツールでの使用

@McpTool(name = "long-operation", description = "Long-running operation with progress")
public String performLongOperation(
        @McpProgressToken String progressToken,
        @McpToolParam(description = "Operation name", required = true) String operation,
        @McpToolParam(description = "Duration in seconds", required = true) int duration,
        McpSyncServerExchange exchange) {

    if (progressToken != null) {
        // Send initial progress
        exchange.progressNotification(ProgressNotification.builder(progressToken, 0.0)
            .total(1.0).message("Starting " + operation).build());

        // Simulate work with progress updates
        for (int i = 1; i <= duration; i++) {
            Thread.sleep(1000);
            double progress = (double) i / duration;

            exchange.progressNotification(ProgressNotification.builder(progressToken, progress)
                .total(1.0).message(String.format("Processing... %d%%", (int)(progress * 100))).build());
        }
    }

    return "Operation " + operation + " completed";
}

リソースでの使用

@McpResource(uri = "large-file://{path}", name = "Large File Resource")
public ReadResourceResult getLargeFile(
        @McpProgressToken String progressToken,
        String path,
        McpSyncServerExchange exchange) {

    File file = new File(path);
    long fileSize = file.length();

    if (progressToken != null) {
        // Track file reading progress
        exchange.progressNotification(ProgressNotification.builder(progressToken, 0.0)
            .total(fileSize).message("Reading file").build());
    }

    String content = readFileWithProgress(file, progressToken, exchange);

    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, fileSize)
            .total(fileSize).message("File read complete").build());
    }

    return ReadResourceResult.builder(List.of(
        new TextResourceContents("large-file://" + path, "text/plain", content)
    )).build();
}

McpSyncRequestContext/McpAsyncRequestContext

リクエストコンテキストオブジェクトは、MCP リクエスト情報とサーバー側操作への統合されたアクセスを提供します。

概要

ステートフル操作とステートレス操作の両方に統一されたインターフェースを提供します
パラメーターとして使用すると自動的に挿入されます
JSON スキーマ生成から除外
ログ記録、進捗通知、サンプリング、情報収集、ルートアクセスなどの高度な機能を有効にします。
ステートフル（サーバー交換）モードとステートレス（トランスポートコンテキスト）モードの両方で動作します

コンテキスト Getter

McpSyncRequestContext と McpAsyncRequestContext はどちらも、以下の読み取り専用コンテキストを公開します。

メソッド説明

メソッド	説明
`request()`	元の MCP リクエスト（例: `CallToolRequest`、`ReadResourceRequest`）。進行状況トークンにアクセスするには、`request().progressToken()` を使用します。
`exchange()`	基盤となるサーバー交換（`McpSyncServerExchange` / `McpAsyncServerExchange`）。ステートフルモードでのみ利用可能。ステートレスモードでは `null` が利用可能。
`sessionId()`	現在のセッション識別子。
`clientInfo()`	クライアント実装情報（`Implementation`）。
`clientCapabilities()`	クライアントが宣言した機能。
`requestMeta()`	リクエストの `_meta` フィールドから取得したメタデータマップ。コンテキストオブジェクトをすでに使用している場合は、`McpMeta` を挿入するよりもこちらを使用することをお勧めします。
`transportContext()`	The transport-level context (`McpTransportContext`).

request()

元の MCP リクエスト（例: CallToolRequest、ReadResourceRequest）。進行状況トークンにアクセスするには、request().progressToken() を使用します。

exchange()

基盤となるサーバー交換（McpSyncServerExchange / McpAsyncServerExchange）。ステートフルモードでのみ利用可能。ステートレスモードでは null が利用可能。

sessionId()

現在のセッション識別子。

clientInfo()

クライアント実装情報（Implementation）。

clientCapabilities()

クライアントが宣言した機能。

requestMeta()

リクエストの _meta フィールドから取得したメタデータマップ。コンテキストオブジェクトをすでに使用している場合は、McpMeta を挿入するよりもこちらを使用することをお勧めします。

transportContext()

The transport-level context (McpTransportContext).

McpSyncRequestContext の機能

public record UserInfo(String name, String email, int age) {}

@McpTool(name = "advanced-tool", description = "Tool with full server capabilities")
public String advancedTool(
        McpSyncRequestContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    // Send logging notification
    context.info("Processing: " + input);

    // Ping the client
    context.ping();

    // Send progress updates
    context.progress(50); // 50% complete

    // Check if elicitation is supported before using it
    if (context.elicitEnabled()) {
        // Request additional information from user
        StructuredElicitResult<UserInfo> elicitResult = context.elicit(
            e -> e.message("Need additional information"),
            UserInfo.class
        );

        if (elicitResult.action() == ElicitResult.Action.ACCEPT) {
            UserInfo userInfo = elicitResult.structuredContent();
            // Use the user information
        }
    }

    // Check if sampling is supported before using it
    if (context.sampleEnabled()) {
        // Request LLM sampling
        CreateMessageResult samplingResult = context.sample(
            s -> s.message("Process: " + input)
                .modelPreferences(pref -> pref.modelHints("gpt-4"))
        );
    }

    // Access client root directories (only available in stateful mode)
    if (context.rootsEnabled()) {
        ListRootsResult roots = context.roots();
        roots.roots().forEach(root -> context.info("Client root: " + root.uri()));
    }

    return "Processed with advanced features";
}

McpAsyncRequestContext の機能

public record UserInfo(String name, String email, int age) {}

@McpTool(name = "async-advanced-tool", description = "Async tool with server capabilities")
public Mono<String> asyncAdvancedTool(
        McpAsyncRequestContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    return context.info("Async processing: " + input)
        .then(context.progress(25))
        .then(context.ping())
        .flatMap(v -> {
            // Perform elicitation if supported
            if (context.elicitEnabled()) {
                return context.elicitation(UserInfo.class)
                    .map(userInfo -> "Processing for user: " + userInfo.name());
            }
            return Mono.just("Processing...");
        })
        .flatMap(msg -> {
            // Perform sampling if supported
            if (context.sampleEnabled()) {
                return context.sampling("Process: " + input)
                    .map(result -> "Completed: " + result);
            }
            return Mono.just("Completed: " + msg);
        });
}

McpTransportContext

ステートレス操作のための軽量コンテキスト。

概要

完全なサーバー交換なしで最小限のコンテキストを提供します
ステートレス実装で使用される
パラメーターとして使用すると自動的に挿入されます
JSON スキーマ生成から除外

使用例

@McpTool(name = "stateless-tool", description = "Stateless tool with context")
public String statelessTool(
        McpTransportContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    // Limited context access
    // Useful for transport-level operations

    return "Processed in stateless mode: " + input;
}

@McpResource(uri = "stateless://{id}", name = "Stateless Resource")
public ReadResourceResult statelessResource(
        McpTransportContext context,
        String id) {

    // Access transport context if needed
    String data = loadData(id);

    return ReadResourceResult.builder(List.of(
        new TextResourceContents("stateless://" + id, "text/plain", data)
    )).build();
}

CallToolRequest

動的スキーマを使用して完全なリクエストにアクセスする必要があるツールの特別なパラメーター。

概要

完全なツールリクエストへのアクセスを提供します
実行時に動的なスキーマ処理を可能にする
スキーマ生成から自動的に挿入および除外されます
さまざまな入力スキーマに適応する柔軟なツールに役立ちます

使用例

@McpTool(name = "dynamic-tool", description = "Tool with dynamic schema support")
public CallToolResult processDynamicSchema(CallToolRequest request) {
    Map<String, Object> args = request.arguments();

    // Process based on whatever schema was provided at runtime
    StringBuilder result = new StringBuilder("Processed:\n");

    for (Map.Entry<String, Object> entry : args.entrySet()) {
        result.append("  ").append(entry.getKey())
              .append(": ").append(entry.getValue()).append("\n");
    }

    return CallToolResult.builder()
        .addTextContent(result.toString())
        .build();
}

混合パラメーター

@McpTool(name = "hybrid-tool", description = "Tool with typed and dynamic parameters")
public String processHybrid(
        @McpToolParam(description = "Operation", required = true) String operation,
        @McpToolParam(description = "Priority", required = false) Integer priority,
        CallToolRequest request) {

    // Use typed parameters for known fields
    String result = "Operation: " + operation;
    if (priority != null) {
        result += " (Priority: " + priority + ")";
    }

    // Access additional dynamic arguments
    Map<String, Object> allArgs = request.arguments();

    // Remove known parameters to get only additional ones
    Map<String, Object> additionalArgs = new HashMap<>(allArgs);
    additionalArgs.remove("operation");
    additionalArgs.remove("priority");

    if (!additionalArgs.isEmpty()) {
        result += " with " + additionalArgs.size() + " additional parameters";
    }

    return result;
}

進捗トークンを使用する場合

@McpTool(name = "flexible-with-progress", description = "Flexible tool with progress")
public CallToolResult flexibleWithProgress(
        @McpProgressToken String progressToken,
        CallToolRequest request,
        McpSyncServerExchange exchange) {

    Map<String, Object> args = request.arguments();

    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, 0.0)
            .total(1.0).message("Processing dynamic request").build());
    }

    // Process dynamic arguments
    String result = processDynamicArgs(args);

    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, 1.0)
            .total(1.0).message("Complete").build());
    }

    return CallToolResult.builder()
        .addTextContent(result)
        .build();
}

パラメーター注入ルール

自動注入

次のパラメーターはフレームワークによって自動的に挿入されます。

McpMeta - Metadata from the _meta field of the request
@McpProgressToken String - 進捗トークン（利用可能な場合）
McpSyncRequestContext / McpAsyncRequestContext - Unified request context (推奨)
McpSyncServerExchange / McpAsyncServerExchange - Low-level server exchange context (stateful only)
McpTransportContext - ステートレス操作のトランスポートコンテキスト
CallToolRequest - 動的スキーマの完全なツールリクエスト (ツールのみ)

スキーマ生成

特別なパラメーターは JSON スキーマ生成から除外されます。

ツールの入力スキーマには表示されない
パラメーター制限にはカウントされません
MCP クライアントには表示されません

Null 処理

McpMeta - メタデータがない場合、null になることはありません。空のオブジェクトです。
@McpProgressToken - トークンが提供されていない場合は null になることがあります
サーバー交換 - 適切に構成されている場合は null になりません
CallToolRequest - ツールメソッドでは null にはなりません

ベストプラクティス

コンテキストには McpMeta を使用する

@McpTool(name = "context-aware", description = "Context-aware tool")
public String contextAware(
        @McpToolParam(description = "Data", required = true) String data,
        McpMeta meta) {

    // Always check for null values in metadata
    String userId = (String) meta.get("userId");
    if (userId == null) {
        userId = "anonymous";
    }

    return processForUser(data, userId);
}

プログレストークンの Null チェック

@McpTool(name = "safe-progress", description = "Safe progress handling")
public String safeProgress(
        @McpProgressToken String progressToken,
        @McpToolParam(description = "Task", required = true) String task,
        McpSyncServerExchange exchange) {

    // Always check if progress token is available
    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, 0.0)
            .total(1.0).message("Starting").build());
    }

    // Perform work...

    if (progressToken != null) {
        exchange.progressNotification(ProgressNotification.builder(progressToken, 1.0)
            .total(1.0).message("Complete").build());
    }

    return "Task completed";
}

適切なコンテキストを選択する

リクエストコンテキストへの統一されたアクセスのために McpSyncRequestContext / McpAsyncRequestContext を使用し、便利なヘルパーメソッドでステートフル操作とステートレス操作の両方をサポートします。
トランスポートレベルのコンテキストのみが必要な場合は、単純なステートレス操作に McpTransportContext を使用します。
最も単純なケースではコンテキストパラメーターを完全に省略する

機能確認

クライアント機能を使用する前に、必ず機能のサポートを確認してください。

@McpTool(name = "capability-aware", description = "Tool that checks capabilities")
public String capabilityAware(
        McpSyncRequestContext context,
        @McpToolParam(description = "Data", required = true) String data) {

    // Check if elicitation is supported before using it
    if (context.elicitEnabled()) {
        // Safe to use elicitation
        var result = context.elicit(UserInfo.class);
        // Process result...
    }

    // Check if sampling is supported before using it
    if (context.sampleEnabled()) {
        // Safe to use sampling
        var samplingResult = context.sample("Process: " + data);
        // Process result...
    }

    // Note: Stateless servers do not support bidirectional operations
    // (roots, elicitation, sampling) and will return false for these checks

    return "Processed with capability awareness";
}

MCP アノテーションの特殊パラメーター

特殊なパラメーター型

MetaProvider

概要

カスタム MetaProvider

McpMeta

概要

ツールでの使用

リソースでの使用

プロンプトでの使用

@McpProgressToken

概要

ツールでの使用

リソースでの使用

McpSyncRequestContext/McpAsyncRequestContext

概要

コンテキスト Getter

McpSyncRequestContext の機能

McpAsyncRequestContext の機能

McpTransportContext

概要

使用例

CallToolRequest

概要

使用例

混合パラメーター

進捗トークンを使用する場合

パラメーター注入ルール

自動注入

スキーマ生成

Null 処理

ベストプラクティス

コンテキストには McpMeta を使用する

プログレストークンの Null チェック

適切なコンテキストを選択する

機能確認

追加リソース