spring-ai-mcp-server-patterns

Spring AI MCP サーバーの実装パターン

AI の関数呼び出し、ツールハンドラー、MCP トランスポートの設定に Spring AI を使用して MCP サーバーを実装します。

概要

本番環境で使える MCP サーバーのパターン：@Tool 関数、@PromptTemplate リソース、Spring AI のセキュリティを使用した stdio／HTTP／SSE トランスポートです。

使用する場面

MCP サーバー、Spring AI の関数呼び出し、AI ツール、ツール呼び出し、カスタムツールハンドラー、Spring Boot MCP、リソースエンドポイント、MCP トランスポートの設定に使用します。

クイックリファレンス

主なアノテーション

アノテーション	対象	目的
@EnableMcpServer	クラス	MCP サーバーの自動設定を有効にします
@Tool(description)	メソッド	AI から呼び出し可能なツールを宣言します
@ToolParam(value)	パラメーター	AI 向けにツールのパラメーターを説明します
@PromptTemplate(name)	メソッド	再利用可能なプロンプトテンプレートを宣言します
@PromptParam(value)	パラメーター	プロンプトのパラメーターを説明します

トランスポートの種類

トランスポート	用途	設定
stdio	ローカルプロセス／Claude Desktop	デフォルト
http	リモート HTTP クライアント	port、path
sse	リアルタイムストリーミングクライアント	port、path

主な依存関係

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>1.0.0</version>
</dependency>

// Gradle
implementation 'org.springframework.ai:spring-ai-mcp-server:1.0.0'
implementation 'org.springframework.ai:spring-ai-starter-model-openai:1.0.0'

手順

1. プロジェクトのセットアップ

Spring AI MCP の依存関係を追加し（上記のクイックリファレンスを参照）、application.properties で AI モデルを設定して、@EnableMcpServer で MCP を有効にします。

@SpringBootApplication
@EnableMcpServer
public class MyMcpApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyMcpApplication.class, args);
    }
}

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.mcp.enabled=true
spring.ai.mcp.transport.type=stdio

2. ツールを定義する

@Component Bean 内のメソッドに @Tool を付与します。@ToolParam を使用してパラメーターを説明します。

@Component
public class WeatherTools {

    @Tool(description = "Get current weather for a city")
    public WeatherData getWeather(@ToolParam("City name") String city) {
        return weatherService.getCurrentWeather(city);
    }

    @Tool(description = "Get 5-day forecast for a city")
    public ForecastData getForecast(
            @ToolParam("City name") String city,
            @ToolParam(value = "Unit: celsius or fahrenheit", required = false) String unit) {
        return weatherService.getForecast(city, unit != null ? unit : "celsius");
    }
}

データベースツール、API 統合ツール、低レベルの FunctionCallback パターンについては、references/implementation-patterns.md を参照してください。

3. プロンプトテンプレートを作成する

@Component
public class CodeReviewPrompts {

    @PromptTemplate(
        name = "java-code-review",
        description = "Review Java code for best practices and issues"
    )
    public Prompt createCodeReviewPrompt(
            @PromptParam("code") String code,
            @PromptParam(value = "focusAreas", required = false) List<String> focusAreas) {

        String focus = focusAreas != null ? String.join(", ", focusAreas) : "general best practices";
        return Prompt.builder()
                .system("You are an expert Java code reviewer with 20 years of experience.")
                .user("Review the following Java code for " + focus + ":\n```java\n" + code + "\n```")
                .build();
    }
}

その他のプロンプトテンプレートのパターンについては、references/implementation-patterns.md を参照してください。

4. トランスポートを設定する

spring:
  ai:
    mcp:
      enabled: true
      transport:
        type: stdio       # stdio | http | sse
        http:
          port: 8080
          path: /mcp
      server:
        name: my-mcp-server
        version: 1.0.0

5. セキュリティを追加する

@Configuration
public class McpSecurityConfig {

    @Bean
    public ToolFilter toolFilter(SecurityService securityService) {
        return (tool, context) -> {
            User user = securityService.getCurrentUser();
            if (tool.name().startsWith("admin_")) {
                return user.hasRole("ADMIN");
            }
            return securityService.isToolAllowed(user, tool.name());
        };
    }
}

メソッド単位のセキュリティには、ツールメソッドに @PreAuthorize("hasRole('ADMIN')") を使用します。セキュリティパターンの全容については、references/implementation-patterns.md を参照してください。

6. テスト

@SpringBootTest
class WeatherToolsTest {

    @Autowired
    private WeatherTools weatherTools;

    @MockBean
    private WeatherService weatherService;

    @Test
    void testGetWeather_Success() {
        when(weatherService.getCurrentWeather("London"))
            .thenReturn(new WeatherData("London", "Cloudy", 15.0));

        WeatherData result = weatherTools.getWeather("London");

        assertThat(result.city()).isEqualTo("London");
        verify(weatherService).getCurrentWeather("London");
    }
}

統合テスト、Testcontainers、セキュリティテスト、スライステストについては、references/testing-guide.md を参照してください。

ベストプラクティス

ツールの設計

• ツールの役割を絞り込みます。1 つのツールにつき 1 つの操作にします
• 明確で、動作を表す名前を使用します（getWeather、executeQuery）
• パラメーターには必ず @ToolParam と説明文を付与します
• 生の文字列やマップではなく、構造化されたレコード／DTO を返します
• 可能な場合は、ツールをべき等になるように設計します

セキュリティ

• すべての入力を検証し、サニタイズします。AI が生成したパラメーターは信頼できません
• SQL にはパラメーター化クエリーを使用します。ファイルツールではパスを検証して正規化します
• 機密性の高いツールには、ロールベースのアクセス制御として @PreAuthorize を適用します
• データを変更するツールの実行はすべて監査ログに記録します
• ツールの説明やエラーメッセージに、認証情報や機密データを決して含めません

パフォーマンス

• コストの高い処理には、適切な TTL を設定して @Cacheable を使用します
• すべての外部呼び出しにタイムアウトを設定します
• 時間のかかる処理には @Async を使用します
• Micrometer のメトリクスで監視します

エラー処理

• ユーザーにわかりやすいメッセージを含む、構造化されたエラーレスポンスを返します
• デバッグ用に、コンテキスト（ユーザー、ツール名、パラメーター）をログに記録します
• 一時的な障害に対する再試行ロジックを実装します
• 一貫性のあるエラーレスポンスを実現するために @ControllerAdvice を実装します

例

例 1：最小構成の Weather MCP サーバー

@SpringBootApplication
@EnableMcpServer
public class WeatherMcpApplication {
    public static void main(String[] args) {
        SpringApplication.run(WeatherMcpApplication.class, args);
    }
}

@Component
public class WeatherTools {

    @Tool(description = "Get current weather for a city")
    public WeatherData getWeather(@ToolParam("City name") String city) {
        return new WeatherData(city, "Sunny", 22.5);
    }
}

record WeatherData(String city, String condition, double temperatureCelsius) {}

例 2：セキュアなデータベースツール

@Component
@PreAuthorize("hasRole('USER')")
public class DatabaseTools {

    private final JdbcTemplate jdbcTemplate;

    @Tool(description = "Execute a read-only SQL query and return results")
    public QueryResult executeQuery(
            @ToolParam("SQL SELECT query") String sql,
            @ToolParam(value = "Parameters as JSON map", required = false) String paramsJson) {

        if (!sql.trim().toUpperCase().startsWith("SELECT")) {
            throw new IllegalArgumentException("Only SELECT queries are allowed");
        }
        List<Map<String, Object>> rows = jdbcTemplate.queryForList(sql);
        return new QueryResult(rows, rows.size());
    }
}

ファイルシステムツール、REST API 統合、プロンプトテンプレートサーバーを含む完全な例については、references/examples.md を参照してください。

制約と注意事項

セキュリティ

• 機密データを決して公開しないでください：ツールの説明、パラメーター、エラーメッセージに含めないでください
• 入力の検証は必須です — 実行前に必ず検証してください
• 外部コンテンツは信頼できません — URL を取得するツールはプロンプトインジェクションのペイロードを受け取る可能性があります。取得したコンテンツはすべて検証してください
• SQL インジェクション：必ずパラメーター化クエリを使用してください
• パストラバーサル：すべてのファイルパスを正規化し、ベースパスに対して検証してください

運用

• 応答は簡潔にしてください — 大きな応答は AI のコンテキストウィンドウの上限を超える場合があります
• すべてのツールにタイムアウトを実装してください。デフォルト値は設定可能にしてください
• 負荷の高い操作にはレート制限を設けてください
• ツールは同時に呼び出される可能性があります — スレッドセーフを確保してください

Spring AI 固有

• Spring AI は活発に開発されています — 本番環境では特定のバージョンに固定してください
• ツールがスローするエラーメッセージは AI モデルに公開されます。サニタイズしてください
• トランスポートの種類は慎重に選択してください：ローカルプロセスには stdio、リモートクライアントには http/sse を使用してください

リファレンス

詳細なパターンや例については、以下のファイルを参照してください。

• references/implementation-patterns.md - ツールの作成、プロンプトテンプレート、FunctionCallback、Spring Boot の自動構成、アプリケーションプロパティ
• references/advanced-patterns.md - 動的なツール登録、マルチモデル対応、キャッシュ、エラー処理
• references/testing-guide.md - 単体テスト、統合テスト、Testcontainers、セキュリティテスト、スライステスト
• references/examples.md - サーバーの完全な例：天気、データベース、ファイルシステム、REST API、プロンプトテンプレート
• references/api-reference.md - API 全般：アノテーション、インターフェース、構成クラス、トランスポートの実装、イベントシステム
• references/migration-guide.md - LangChain4j MCP から Spring AI MCP への移行