MCP Client

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-ollama</artifactId>
    </dependency>
</dependencies>

spring.ai.mcp.client.type=SYNC
spring.ai.mcp.client.request-timeout=30s
spring.ai.mcp.client.streamable-http.connections.github.url=https://api.githubcopilot.com
spring.ai.mcp.client.streamable-http.connections.github.endpoint=/mcp/readonly

package com.example.docsassistant;

import java.time.Duration;

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
import org.springframework.ai.mcp.McpToolFilter;
import org.springframework.ai.mcp.customizer.McpClientCustomizer;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
class DocsMcpClientConfig {

    // Called once per streamable-http connection, with the connection's name from the properties.
    // The token is read from the environment and goes to the "github" connection only.
    @Bean
    McpClientCustomizer<HttpClientStreamableHttpTransport.Builder> githubToken(
            @Value("${GITHUB_MCP_TOKEN}") String token) {
        return (connectionName, transport) -> {
            if ("github".equals(connectionName)) {
                transport.httpRequestCustomizer((request, method, uri, body, transportContext) ->
                        request.header("Authorization", "Bearer " + token));
            }
        };
    }

    // Called once per client, whatever its transport: timeouts, roots and the handlers of the spec
    @Bean
    McpClientCustomizer<McpClient.SyncSpec> clientTimeouts() {
        return (connectionName, spec) ->
                spec.requestTimeout(Duration.ofSeconds("github".equals(connectionName) ? 60 : 20));
    }

    // Deny by default: only tools that declare themselves read-only reach the model
    @Bean
    McpToolFilter readOnlyToolsOnly() {
        return (connection, tool) -> tool.annotations() != null
                && Boolean.TRUE.equals(tool.annotations().readOnlyHint());
    }
}

package com.example.docsassistant;

import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
import org.springaicommunity.mcp.security.client.sync.oauth2.http.client.OAuth2ClientCredentialsSyncHttpRequestCustomizer;
import org.springframework.ai.mcp.customizer.McpClientCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.security.oauth2.client.AuthorizedClientServiceOAuth2AuthorizedClientManager;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientProviderBuilder;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;

/** DocsAssistant calling its own protected MCP server as a service: a client-credentials token per request. */
@Configuration(proxyBeanMethods = false)
@Profile("oauth")
class McpOAuthClientConfig {

    @Bean
    AuthorizedClientServiceOAuth2AuthorizedClientManager mcpAuthorizedClients(
            ClientRegistrationRepository registrations, OAuth2AuthorizedClientService authorizedClients) {
        var manager = new AuthorizedClientServiceOAuth2AuthorizedClientManager(registrations, authorizedClients);
        manager.setAuthorizedClientProvider(OAuth2AuthorizedClientProviderBuilder.builder().clientCredentials().build());
        return manager;
    }

    @Bean
    McpClientCustomizer<HttpClientStreamableHttpTransport.Builder> docsServerToken(
            AuthorizedClientServiceOAuth2AuthorizedClientManager manager) {
        // "docs-mcp" is the name of the spring.security.oauth2.client.registration entry
        var customizer = new OAuth2ClientCredentialsSyncHttpRequestCustomizer(manager, "docs-mcp");
        return (connectionName, transport) -> {
            if ("docs".equals(connectionName)) {
                transport.httpRequestCustomizer(customizer);
            }
        };
    }
}

package com.example.docsassistant;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.stereotype.Service;

@Service
class GithubIssueAssistant {

    private final ChatClient chatClient;

    // SyncMcpToolCallbackProvider is the bean the starter registers: the tools of every connection, after filtering
    GithubIssueAssistant(ChatClient.Builder builder, SyncMcpToolCallbackProvider mcpTools) {
        this.chatClient = builder
                .defaultSystem("""
                        You answer questions about the issues and pull requests of the documentation repositories.
                        Use the tools; if they return nothing useful, say so instead of guessing.
                        """)
                .defaultTools(mcpTools)
                .build();
    }

    String ask(String question) {
        return this.chatClient.prompt().user(question).call().content();
    }
}

package com.example.docsassistant;

import java.util.List;

import io.modelcontextprotocol.spec.McpSchema;
import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
import io.modelcontextprotocol.spec.McpSchema.ProgressNotification;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.mcp.annotation.McpElicitation;
import org.springframework.ai.mcp.annotation.McpLogging;
import org.springframework.ai.mcp.annotation.McpProgress;
import org.springframework.ai.mcp.annotation.McpToolListChanged;
import org.springframework.stereotype.Component;

/** Handlers for what a server sends on its own. "github" is the connection name from the properties. */
@Component
class McpClientHandlers {

    private static final Logger log = LoggerFactory.getLogger(McpClientHandlers.class);

    @McpLogging(clients = "github")
    void onLog(LoggingMessageNotification notification) {
        // server-controlled text: log the level and the logger, and keep the message out of prompts
        log.info("MCP server log [{}] from {}", notification.level(), notification.logger());
    }

    @McpProgress(clients = "github")
    void onProgress(ProgressNotification notification) {
        Double total = notification.total();
        log.info("MCP progress {} of {}", notification.progress(), total == null ? "?" : total);
    }

    @McpToolListChanged(clients = "github")
    void onToolsChanged(List<McpSchema.Tool> tools) {
        log.info("The GitHub server now offers {} tools", tools.size());   // the tool callback provider refreshes itself
    }

    // A headless service has nobody to ask, so every elicitation is declined
    @McpElicitation(clients = "github")
    ElicitResult onElicit(ElicitRequest request) {
        log.warn("Declining an elicitation request from the GitHub server");
        return new ElicitResult(ElicitResult.Action.DECLINE, null);
    }
}

package com.example.docsassistant;

import java.util.List;

import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.spec.McpSchema.Tool;
import org.springframework.stereotype.Component;

/** The starter also exposes each connection as an McpSyncClient bean, for calls outside a chat. */
@Component
class McpConnectionInventory {

    private final List<McpSyncClient> clients;

    McpConnectionInventory(List<McpSyncClient> clients) {
        this.clients = clients;
    }

    List<String> toolNames() {
        return this.clients.stream()
                .flatMap(client -> client.listTools().tools().stream())
                .map(Tool::name)
                .sorted()
                .toList();
    }
}