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

主要な依存関係

<!-- Maven -->
<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 ビーン内のメソッドに @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 つの操作
• 明確でアクション指向の名前を使用 (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 - 完全なサーバー例: weather、database、file system、REST API、prompt templates
• references/api-reference.md - 完全な API: アノテーション、インターフェース、設定クラス、トランスポート実装、イベントシステム
• references/migration-guide.md - LangChain4j MCP から Spring AI MCP への移行