MCP Security

https://github.com/spring-ai-community/mcp-security
Admin
MCP Security provides OAuth 2.0 authentication and authorization support for Model Context Protocol...
Tokens:49,698
Snippets:604
Trust Score:8.6
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example WWW-Authenticate Headers

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

Illustrative examples of WWW-Authenticate header values, demonstrating different parameter formats.

```text
WWW-Authenticate: Bearer resource="http://localhost:8090/.well-known/mcp.json"
WWW-Authenticate: Bearer error="insufficient_scope", scope="openid profile"
```

--------------------------------

### Usage Example for InMemoryApiKeyEntityRepository

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/api-key-entity-repository.md

Provides an example of creating and initializing an InMemoryApiKeyEntityRepository with sample API key entities.

```java
var key1 = ApiKeyEntityImpl.builder()
    .id("api01")
    .name("Key 1")
    .secret("raw-secret-1")
    .build();

var key2 = ApiKeyEntityImpl.builder()
    .id("api02")
    .name("Key 2")
    .secret("raw-secret-2")
    .build();

ApiKeyEntityRepository<ApiKeyEntityImpl> repo = 
    new InMemoryApiKeyEntityRepository<>(List.of(key1, key2));

```

--------------------------------

### ApiKeyAuthenticationProvider Example Usage

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Provides an example of how to create an ApiKeyAuthenticationProvider with an in-memory repository and an ApiKeyEntity.

```java
ApiKeyEntityRepository<ApiKeyEntityImpl> repo = new InMemoryApiKeyEntityRepository<>(keys);
AuthenticationProvider provider = new ApiKeyAuthenticationProvider<>(repo);
```

--------------------------------

### Manual Security Filter Chain Setup

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Java configuration for activating authorization server capabilities in a manual setup.

```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) {
    return http
            // all requests must be authenticated
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            // enable authorization server customizations
            .with(McpAuthorizationServerConfigurer.mcpAuthorizationServer(), withDefaults())
            // enable form-based login, for user "user"/"password"
            .formLogin(withDefaults())
            .build();
}
```

--------------------------------

### Usage Example for McpMetadataDiscoveryService

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

This example demonstrates how to use the discoverAuthorizationServer method to fetch and process resource metadata. It includes error handling for common exceptions like InvalidUrlException and RestClientException.

```java
String metadataUrl = "http://localhost:8090/.well-known/mcp.json";
try {
    ProtectedResourceMetadata metadata = discoveryService.discoverAuthorizationServer(metadataUrl);
    String authServerUri = metadata.authorizationServerUri();
    Set<String> scopes = metadata.scopes();
    // Use metadata for client registration
} catch (InvalidUrlException e) {
    logger.warn("Metadata URL validation failed: {}", e.getMessage());
} catch (RestClientException e) {
    logger.error("Failed to fetch resource metadata: {}", e.getMessage());
}
```

--------------------------------

### Example OAuth2 Client Registration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

An example demonstrating the configuration of an OAuth2 client named 'authserver' with specific client ID, secret, grant type, and provider URIs.

```properties
spring.security.oauth2.client.registration.authserver.client-id=my-client
spring.security.oauth2.client.registration.authserver.client-secret=my-secret
spring.security.oauth2.client.registration.authserver.authorization-grant-type=authorization_code

spring.security.oauth2.client.provider.authserver.token-uri=http://localhost:9000/oauth2/token
spring.security.oauth2.client.provider.authserver.authorization-uri=http://localhost:9000/oauth2/authorize
```

--------------------------------

### Example Response Header

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Illustrates the format of the WWW-Authenticate header returned by the entry point.

```http
WWW-Authenticate: Bearer resource="http://localhost:8090/mcp"
```

--------------------------------

### Run Authorization Server with Maven

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Starts the authorization server using Maven. This server issues access tokens required by MCP servers. Ensure this is running before starting the MCP server.

```shell
./mvnw spring-boot:run -pl samples/sample-authorization-server
```

--------------------------------

### Instantiate DelegatingRegisteredClientRepository

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/types.md

Example of creating a DelegatingRegisteredClientRepository with in-memory and CIMD/DCR repositories.

```java
RegisteredClientRepository delegating = new DelegatingRegisteredClientRepository(
    new InMemoryRegisteredClientRepository(existingClients),
    new ClientIdMetadataDocumentRegisteredClientRepository()
);
```

--------------------------------

### Example Usage of OAuth2AuthorizationCodeSyncHttpRequestCustomizer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/http-request-customizers.md

Demonstrates how to create an instance of the customizer using provided client manager, repository, and a client registration ID.

```java
var customizer = new OAuth2AuthorizationCodeSyncHttpRequestCustomizer(
    clientManager,
    registrationRepository,
    "my-client"
);
```

--------------------------------

### Example Usage of McpAuthorizationServerConfigurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authorization-server-configurer.md

Demonstrates how to integrate the McpAuthorizationServerConfigurer into the Spring Security filter chain.

```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) {
    return http
        .with(McpAuthorizationServerConfigurer.mcpAuthorizationServer(), withDefaults())
        .formLogin(withDefaults())
        .build();
}
```

--------------------------------

### Run Secured Tools Server

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Starts the MCP server with method-level security enabled for specific tools. Requires the authorization server to be running.

```shell
./mvnw spring-boot:run -pl samples/sample-mcp-server-secured-tools
```

--------------------------------

### Add mcp-authorization-server-spring-boot Dependency (Gradle)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Include this Gradle dependency for quick setup using Boot auto-configuration.

```groovy
implementation("org.springaicommunity:mcp-authorization-server-spring-boot:0.1.13")
```

--------------------------------

### In-Memory ApiKeyEntityRepository Setup

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Sets up an in-memory repository for API keys using a Java Bean. This is useful for testing or simple configurations.

```java
@Bean
ApiKeyEntityRepository<ApiKeyEntityImpl> apiKeyRepository() {
    var key = ApiKeyEntityImpl.builder()
        .id("api01")
        .name("Production Key")
        .secret("secret-value")
        .build();
    return new InMemoryApiKeyEntityRepository<>(List.of(key));
}
```

--------------------------------

### MCP Authorization Server Configuration (application.yml)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Example application.yml for registering a default client and configuring session cookies.

```yaml
spring:
  application:
    name: sample-authorization-server
  security:
    oauth2:
      authorizationserver:
        client:
          default-client:
            token:
              access-token-time-to-live: 1h
            registration:
              client-id: "default-client"
              client-secret: "{noop}default-secret"
              client-authentication-methods:
                - "client_secret_basic"
                - "none"
              authorization-grant-types:
                - "authorization_code"
                - "client_credentials"
              redirect-uris:
                - "http://127.0.0.1:8080/authorize/oauth2/code/authserver"
                - "http://localhost:8080/authorize/oauth2/code/authserver"
                # mcp-inspector
                - "http://localhost:6274/oauth/callback"
                # claude code
                - "https://claude.ai/api/mcp/auth_callback"
    user:
      # A single user, named "user"
      name: user
      password: password

server:
  servlet:
    session:
      cookie:
        # Override the default cookie name (JSESSIONID).
        # This allows running multiple Spring apps on localhost, and they'll each have their own cookie.
        # Otherwise, since the cookies do not take the port into account, they are confused.
        name: MCP_AUTHORIZATION_SERVER_SESSIONID
```

--------------------------------

### Add mcp-authorization-server Dependency (Gradle)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Include this Gradle dependency for manual setup and advanced customization.

```groovy
implementation("org.springaicommunity:mcp-authorization-server:0.1.13")
```

--------------------------------

### Custom Component Pattern Example

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/README.md

Illustrates the generic type specification for custom components like ApiKeyEntityRepository.

```java
ApiKeyEntityRepository<ApiKeyEntityImpl> repo = ...;
```

--------------------------------

### Add mcp-authorization-server-spring-boot Dependency (Maven)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Include this Maven dependency for quick setup using Boot auto-configuration.

```xml
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>mcp-authorization-server-spring-boot</artifactId>
    <version>0.1.13</version>
</dependency>
```

--------------------------------

### Run MCP Client (HttpClient)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Starts the MCP client using the JDK's HttpClient for transport. This client demonstrates OAuth 2.0 authentication flow.

```shell
./mvnw spring-boot:run -pl samples/sample-mcp-client
```

--------------------------------

### Configure OAuth2 Client Security Filter Chain

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-client-oauth2-configurer.md

Example of configuring an OAuth2 client security filter chain using McpClientOAuth2Configurer. This setup allows any request to be permitted and disables CSRF protection.

```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
        .with(McpClientOAuth2Configurer.mcpClientOAuth2(), Customizer.withDefaults())
        .csrf(CsrfConfigurer::disable)
        .build();
}
```

--------------------------------

### Java Class Declaration Example

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/00-START-HERE.md

Illustrates the basic structure of a Java class declaration within the documentation.

```java
public class/interface ...

```

--------------------------------

### API Key Header Format Example

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Illustrates the expected format for API keys when transmitted in the 'X-API-Key' header. The key should be in 'id.secret' format.

```text
X-API-Key: api01.my-secret-value
```

--------------------------------

### Run API Key MCP Server

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Starts an MCP server secured with API keys. This server does not require a separate authorization server.

```shell
./mvnw spring-boot:run -pl samples/sample-mcp-server-api-key
```

--------------------------------

### Authorization Server with Dynamic Client Registration (DCR)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authorization-server-configurer.md

This example configures an authorization server to support dynamic client registration. It enables DCR by setting the `dynamicClientRegistration` option to true within the MCP configuration.

```java
@Configuration
@EnableWebSecurity
public class AuthorizationServerConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .with(McpAuthorizationServerConfigurer.mcpAuthorizationServer(), mcp -> {
                mcp.dynamicClientRegistration(true);
            })
            .formLogin(withDefaults())
            .build();
    }
}
```

--------------------------------

### Run MCP Server with Maven

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Starts the MCP server using Maven. This server is protected by OAuth 2.0 and exposes MCP endpoints. It requires the authorization server to be running.

```shell
./mvnw spring-boot:run -pl samples/sample-mcp-server
```

--------------------------------

### Run MCP Client (WebClient)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Starts the MCP client using Spring's reactive WebClient for transport. This client also demonstrates OAuth 2.0 authentication.

```shell
./mvnw spring-boot:run -pl samples/sample-mcp-client-webclient
```

--------------------------------

### Gradle Dependency for Manual MCP Client Security Setup

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Add this Gradle dependency for manual configuration of MCP client security, suitable for non-Boot or advanced use cases.

```groovy
implementation("org.springaicommunity:mcp-client-security:0.1.13")
```

--------------------------------

### Example Response Body

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Shows the JSON body included in the 401 Unauthorized response.

```json
{
  "error": "unauthorized",
  "error_description": "Full authentication is required to access this resource"
}
```

--------------------------------

### Add mcp-authorization-server Dependency (Maven)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Include this Maven dependency for manual setup and advanced customization.

```xml
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>mcp-authorization-server</artifactId>
    <version>0.1.13</version>
</dependency>
```

--------------------------------

### Example WWW-Authenticate Header

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/errors.md

This header is used in 401 Unauthorized responses to indicate required DCR.

```http
WWW-Authenticate: Bearer resource="http://localhost:8090/.well-known/mcp.json"
```

--------------------------------

### Authorization Server with Both DCR and CIMD

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authorization-server-configurer.md

This comprehensive example configures an authorization server to support both Dynamic Client Registration (DCR) and Client Metadata (CIMD). It sets up a `DelegatingRegisteredClientRepository` to combine in-memory clients with CIMD clients.

```java
@Configuration
@EnableWebSecurity
public class AuthorizationServerConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .with(McpAuthorizationServerConfigurer.mcpAuthorizationServer(), mcp -> {
                mcp.dynamicClientRegistration(true)
                   .cimd(true);
            })
            .formLogin(withDefaults())
            .build();
    }

    @Bean
    RegisteredClientRepository registeredClientRepository() {
        var inMemory = new InMemoryRegisteredClientRepository(preRegisteredClients());
        var cimdRepo = cimdRepository();
        return new DelegatingRegisteredClientRepository(inMemory, cimdRepo);
    }

    private ClientIdMetadataDocumentRegisteredClientRepository cimdRepository() {
        var repository = new ClientIdMetadataDocumentRegisteredClientRepository();
        repository.setMetadataDocumentResolver(new DefaultClientIdMetadataDocumentResolver());
        repository.setMetadataValidator(new DefaultClientMetadataValidator(
            new DefaultUrlValidator(false)
        ));
        repository.setClientIdUrlValidator(new ClientIdUrlValidator(false));
        return repository;
    }

    private List<RegisteredClient> preRegisteredClients() {
        return List.of(
            RegisteredClient.withId(UUID.randomUUID().toString())
                .clientId("web-client")
                .clientSecret("{noop}secret")
                .clientAuthenticationMethod(ClientAuthenticationMethod.BASIC)
                .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
                .redirectUri("http://localhost:8080/login/oauth2/code/authserver")
                .scopes(scopes -> scopes.addAll(Set.of("openid", "profile")))
                .build()
        );
    }
}
```

--------------------------------

### Example Usage of OAuth2HttpClientTransportCustomizer with Registration Resolver

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/http-request-customizers.md

Demonstrates how to instantiate OAuth2HttpClientTransportCustomizer using a lambda function to resolve registration IDs based on transport names.

```java
var customizer = new OAuth2HttpClientTransportCustomizer(
    clientManager,
    registrationRepository,
    mcpManager,
    transportName -> "prefix-" + transportName
);
```

--------------------------------

### Example Usage of findByApiKeyId

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/api-key-entity-repository.md

Demonstrates how to use the findByApiKeyId method to retrieve an API key entity and check for its presence.

```java
Optional<ApiKeyEntityImpl> entity = repository.findByApiKeyId("api01");
if (entity.isPresent()) {
    // Validate the secret against entity.get().getSecret()
}

```

--------------------------------

### Configure Security with McpApiKeyConfigurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/api-key-entity-repository.md

Demonstrates how to configure Spring Security to use McpApiKeyConfigurer with a custom ApiKeyEntityRepository. This setup is typically used for API key-based authentication.

```java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;

import com.mcp.security.config.McpApiKeyConfigurer;
import com.mcp.security.repository.ApiKeyEntityRepository;
import com.mcp.security.repository.impl.DatabaseApiKeyEntityRepository;
import com.mcp.security.repository.impl.JpaApiKeyRepository;
import com.mcp.security.dao.ApiKeyDao;
import com.mcp.security.entity.ApiKeyEntity;

@Configuration
@EnableWebSecurity
public class SecurityConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .with(McpApiKeyConfigurer.mcpServerApiKey(), apiKey -> {
                apiKey.apiKeyRepository(apiKeyRepository());
            })
            .build();
    }

    @Bean
    ApiKeyEntityRepository<ApiKeyEntity> apiKeyRepository() {
        // Use custom implementation for production
        return new DatabaseApiKeyEntityRepository(apiKeyDao(), passwordEncoder());
    }

    @Bean
    ApiKeyDao apiKeyDao() {
        return new JpaApiKeyRepository();
    }

    @Bean
    PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}
```

--------------------------------

### Configure MCP Server API Key Security

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-api-key-configurer.md

Example of setting up API key authentication for an MCP server using McpApiKeyConfigurer. This snippet demonstrates how to authorize all requests and configure the API key repository.

```java
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.web.SecurityFilterChain;
import org.springaicommunity.mcp.security.server.config.McpApiKeyConfigurer;

// Assume ApiKeyEntityRepository and apiKeyRepository() are defined elsewhere

public class SecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) {
        return http
            .authorizeHttpRequests(authz -> authz.anyRequest().authenticated())
            .with(McpApiKeyConfigurer.mcpServerApiKey(), apiKey -> {
                apiKey.apiKeyRepository(apiKeyRepository());
            })
            .build();
    }

    // Placeholder for the actual ApiKeyEntityRepository bean or method
    private ApiKeyEntityRepository<?> apiKeyRepository() {
        // Replace with your actual repository implementation
        return null; 
    }
}
```

--------------------------------

### Multi-Module Security Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Configure both MCP Server and MCP Client security in a single application. This example allows all requests to be public, then configures OAuth2 resource server and client functionalities.

```java
@Configuration
@EnableWebSecurity
public class CompositeSecurityConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(CsrfConfigurer::disable)
            .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
            
            // Configure as OAuth2 resource server (MCP Server)
            .with(McpServerOAuth2Configurer.mcpServerOAuth2(), mcpServer -> {
                mcpServer.authorizationServer("http://localhost:9000");
            })
            
            // Configure as OAuth2 client (MCP Client)
            .with(McpClientOAuth2Configurer.mcpClientOAuth2(), mcpClient -> {
                mcpClient.baseUrl("http://localhost:8080")
                         .registerMcpOAuth2Client("remote-server", "http://localhost:8090/mcp");
            })
            
            .build();
    }
}
```

--------------------------------

### Instantiate ApiKeyAuthenticationConverter with Custom Header

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Example of how to instantiate ApiKeyAuthenticationConverter with a custom header name for API key extraction.

```java
AuthenticationConverter converter = new ApiKeyAuthenticationConverter("CUSTOM-API-KEY");
```

--------------------------------

### Client Metadata Document JSON Format

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

Example JSON structure for a client metadata document, used by `ClientIdMetadataDocumentRegisteredClientRepository`.

```json
{
  "client_id": "http://client.example.com/client-id-metadata.json",
  "response_types": ["code"],
  "grant_types": ["authorization_code"],
  "redirect_uris": ["http://client.example.com/callback"],
  "token_endpoint_auth_method": "none",
  "client_name": "My MCP Client"
}
```

--------------------------------

### Configure Security Filter Chain with McpServerOAuth2Configurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-server-oauth2-configurer.md

Example of configuring a SecurityFilterChain using McpServerOAuth2Configurer to secure HTTP requests with JWT bearer tokens.

```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) {
    return http
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .with(McpServerOAuth2Configurer.mcpServerOAuth2(), mcpAuthorization -> {
            mcpAuthorization.authorizationServer("http://localhost:9000");
        })
        .build();
}
```

--------------------------------

### Enable and Configure Session Binding

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-api-key-configurer.md

Enables MCP session binding for API key authentication, ensuring sessions are bound to the originating API key for enhanced security. This example uses default customizer settings.

```java
apiKey.sessionBinding(Customizer.withDefaults());
```

--------------------------------

### Maven Dependency for Manual MCP Client Security Setup

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Use this Maven dependency if you prefer to manually configure beans for MCP client security instead of using the Spring Boot auto-configuration.

```xml
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>mcp-client-security</artifactId>
    <version>0.1.13</version>
</dependency>
```

--------------------------------

### Client Registration Response

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authorization-server-configurer.md

This is an example of the response received after successfully registering a client using DCR. It includes the assigned client ID, secret, and other registration details.

```json
{
  "client_id": "generated-client-id",
  "client_secret": "generated-secret",
  "client_id_issued_at": 1609459200,
  "client_secret_expires_at": 0,
  "registration_access_token": "access-token",
  "registration_client_uri": "http://localhost:9000/oauth2/client_registration/generated-client-id"
}
```

--------------------------------

### Get Resource URI Method

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

Extracts the `resource` parameter from the challenge, used for Dynamic Client Registration (DCR). Returns the resource metadata URL or null if not present.

```java
public String getResourceUri()
```

--------------------------------

### Basic DCR Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-client-oauth2-configurer.md

Configure basic Dynamic Client Registration (DCR) for MCP OAuth2 clients. This snippet shows the minimal setup required to integrate the McpClientOAuth2Configurer.

```java
@Configuration
@EnableWebSecurity
public class SecurityConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
            .with(McpClientOAuth2Configurer.mcpClientOAuth2(), mcpOAuth2 -> {
                mcpOAuth2.baseUrl("http://localhost:8080");
            })
            .csrf(CsrfConfigurer::disable)
            .build();
    }
}
```

--------------------------------

### Handling Insufficient Scope Error Response

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/http-request-customizers.md

Example JSON response indicating an insufficient scope error. This response should be used to guide the re-authorization process.

```json
{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided",
  "scope": "read write admin"
}
```

--------------------------------

### Configuring Hikari Connection Pool Size

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/api-key-entity-repository.md

Optimize database access in high-traffic environments by configuring connection pooling. This example sets the maximum pool size for HikariCP.

```properties
spring.datasource.hikari.maximum-pool-size=20
```

--------------------------------

### Constructor

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Creates an entry point that advertises the resource identifier to unauthenticated clients.

```java
public BearerResourceMetadataTokenAuthenticationEntryPoint(ResourceIdentifier resourceIdentifier)
```

--------------------------------

### Access Authentication Details within a Secured Tool

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

This example shows how to access the current user's authentication details directly within a tool method using SecurityContextHolder. It's secured using @PreAuthorize("isAuthenticated()") and uses the authenticated user's name in the greeting.

```java
@McpTool(name = "greeter", description = "A tool that greets the user by name, in the selected language")
@PreAuthorize("isAuthenticated()")
public String greet(
        @McpToolParam(description = "The language for the greeting (example: english, french, ...)") String language
) {
    if (!StringUtils.hasText(language)) {
        language = "";
    }
    var authentication = SecurityContextHolder.getContext().getAuthentication();
    var name = authentication.getName();
    return switch (language.toLowerCase()) {
        case "english" -> "Hello, %s!".formatted(name);
        case "french" -> "Salut %s!".formatted(name);
        default -> ("I don't understand language \"%s\". " +
                    "So I'm just going to say Hello %s!").formatted(language, name);
    };
}
```

--------------------------------

### Spring Security Configuration with McpClientOAuth2Configurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Configure a SecurityFilterChain in your Spring Boot application to integrate MCP client OAuth2 support. This setup uses the provided McpClientOAuth2Configurer for automatic security setup.

```java
@Configuration
@EnableWebSecurity
class SecurityConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
                .with(McpClientOAuth2Configurer.mcpClientOAuth2(), Customizer.withDefaults())
                .csrf(CsrfConfigurer::disable)
                .build();
    }

}
```

--------------------------------

### Handling InvalidClientMetadataException

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/errors.md

Example of how to catch and handle InvalidClientMetadataException during client metadata processing.

```java
try {
    RegisteredClient client = cimdRepository.findByClientId(clientIdUrl);
} catch (InvalidClientMetadataException e) {
    // Client metadata is invalid
    logger.error("Invalid client metadata: {}", e.getMessage());
    return ResponseEntity.status(400).build();
}
```

--------------------------------

### Commence Method

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Sends a 401 Unauthorized response with a WWW-Authenticate header containing the resource metadata URL.

```java
public void commence(HttpServletRequest request, HttpServletResponse response, 
                     AuthenticationException authException) throws IOException
```

--------------------------------

### MCP Client Initialization and Connection Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Configure MCP client type and initialization behavior. Define URLs for streamable HTTP connections to MCP servers.

```properties
spring.ai.mcp.client.type=SYNC
spring.ai.mcp.client.initialized=false

# Define connections
spring.ai.mcp.client.streamable-http.connections.weather-service.url=http://localhost:8090/mcp
spring.ai.mcp.client.streamable-http.connections.calendar-service.url=http://localhost:8091/mcp
```

--------------------------------

### Handling InvalidUrlException

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/errors.md

Example of how to catch and handle InvalidUrlException during URL validation, particularly for security concerns like SSRF.

```java
try {
    urlValidator.validate("http://localhost:9000");
} catch (InvalidUrlException e) {
    logger.warn("URL validation failed: {}", e.getMessage());
    // Handle SSRF-protected validation failure
}
```

--------------------------------

### Configure Audience Validation JWT Decoder

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Example of how to configure and use the AudienceValidationJwtDecoder. It wraps a standard JwtDecoder with audience validation.

```java
JwtDecoder decoder = new NimbusJwtDecoder.withIssuerLocation(issuerUri).build();
JwtDecoder audienceValidatingDecoder = new AudienceValidationJwtDecoder(
    decoder,
    new ResourceIdentifier("/mcp")
);
```

--------------------------------

### Secure Tool Calls with @PreAuthorize and isAuthenticated()

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

This service demonstrates how to secure a tool method using the @PreAuthorize annotation with the 'isAuthenticated()' SpEL expression. This ensures that only authenticated clients can invoke the 'greet' tool.

```java
@Service
public class MyToolsService {

    // Note: you can also use Spring AI's @Tool
    @PreAuthorize("isAuthenticated()")
    @McpTool(name = "greeter", description = "A tool that greets you, in the selected language")
    public String greet(
            @McpToolParam(description = "The language for the greeting (example: english, french, ...)") String language
    ) {
        if (!StringUtils.hasText(language)) {
            language = "";
        }
        return switch (language.toLowerCase()) {
            case "english" -> "Hello you!";
            case "french" -> "Salut toi!";
            default -> "I don't understand language \"%s\". So I'm just going to say Hello!".formatted(language);
        };
    }

}
```

--------------------------------

### mcpServerApiKey()

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-api-key-configurer.md

Factory method to create a new API key configurer instance. This is the entry point for configuring API key authentication.

```APIDOC
## mcpServerApiKey()

### Description
Factory method to create a new API key configurer instance for fluent chaining.

### Method
`static McpApiKeyConfigurer`

### Returns
`McpApiKeyConfigurer` — new instance for fluent chaining

### Example
```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) {
    return http
        .authorizeHttpRequests(authz -> authz.anyRequest().authenticated())
        .with(McpApiKeyConfigurer.mcpServerApiKey(), apiKey -> {
            apiKey.apiKeyRepository(apiKeyRepository());
        })
        .build();
}
```
```

--------------------------------

### Configure WebClient-based MCP Sync Client

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Manually configure an MCP sync client using WebClient. Requires WebClient.Builder, ObjectMapper, and McpClientCommonProperties. The MCP server URL is set via the WebClient base URL.

```java
// For WebClient based clients
@Bean
McpSyncClient client(
        WebClient.Builder mcpWebClientBuilder,
        ObjectMapper objectMapper,
        McpClientCommonProperties commonProperties
) {
    var builder = mcpWebClientBuilder.baseUrl(mcpServerUrl);
    var transport = WebClientStreamableHttpTransport.builder(builder)
            .jsonMapper(new JacksonMcpJsonMapper(objectMapper))
            .build();

    var clientInfo = new McpSchema.Implementation("clientName", commonProperties.getVersion());

    return McpClient.sync(transport)
            .clientInfo(clientInfo)
            .requestTimeout(commonProperties.getRequestTimeout())
            .transportContextProvider(new AuthenticationMcpTransportContextProvider())
            .build();
}
```

--------------------------------

### Configure HttpClient-based MCP Sync Client

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Manually configure an MCP sync client using HttpClient. Requires ObjectMapper, McpSyncHttpClientRequestCustomizer, and McpClientCommonProperties. Ensure the MCP server URL is correctly set.

```java
// For HttpClient-based clients
@Bean
McpSyncClient client(
        ObjectMapper objectMapper,
        McpSyncHttpClientRequestCustomizer requestCustomizer,
        McpClientCommonProperties commonProps
) {
    var transport = HttpClientStreamableHttpTransport.builder(mcpServerUrl)
            .clientBuilder(HttpClient.newBuilder())
            .jsonMapper(new JacksonMcpJsonMapper(objectMapper))
            .httpRequestCustomizer(requestCustomizer)
            .build();

    var clientInfo = new McpSchema.Implementation("client-name", commonProps.getVersion());

    return McpClient.sync(transport)
            .clientInfo(clientInfo)
            .requestTimeout(commonProps.getRequestTimeout())
            .transportContextProvider(new AuthenticationMcpTransportContextProvider())
            .build();
}
```

--------------------------------

### Configure Authorization Server with McpAuthorizationServerConfigurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Use McpAuthorizationServerConfigurer for fluent configuration of an authorization server. This setup is suitable for applications acting as OAuth2 authorization servers.

```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) {
    return http
        .with(McpAuthorizationServerConfigurer.mcpAuthorizationServer(), mcp -> {
            mcp.dynamicClientRegistration(true)
               .cimd(true);
        })
        .formLogin(Customizer.withDefaults())
        .build();
}
```

--------------------------------

### Auto-Configuration with Properties

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/README.md

Leverage Spring Boot's auto-configuration by setting OAuth2 and MCP server properties.

```properties
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9000
spring.ai.mcp.server.name=my-server
spring.ai.mcp.server.protocol=STREAMABLE
```

--------------------------------

### MCP Client Dynamic Client Registration Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Enable and configure dynamic client registration for MCP clients. Allow loopback addresses for development environments.

```properties
spring.ai.mcp.client.authorization.dynamic-client-registration.enabled=true
spring.ai.mcp.client.authorization.dynamic-client-registration.allow-loopback-addresses=true
```

--------------------------------

### Get Error Method

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

Extracts the `error` parameter from the challenge, used for scope step-up detection. Returns the error code (e.g., `insufficient_scope`) or null.

```java
public String getError()
```

--------------------------------

### WebClient Builder with OAuth2 Filter Function

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Configure a WebClient.Builder with an MCP OAuth2 filter function for reactive transports. This example uses McpOAuth2AuthorizationCodeExchangeFilterFunction for user-level tokens.

```java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
import org.springframework.web.reactive.function.client.WebClient;
import com.mcp.security.webflux.McpOAuth2AuthorizationCodeExchangeFilterFunction;

@Configuration
class McpConfiguration {

    @Bean
    McpSyncClientCustomizer syncClientCustomizer() {
        return (name, syncSpec) ->
                syncSpec.transportContextProvider(
                        new AuthenticationMcpTransportContextProvider()
                );
    }

    @Bean
    WebClient.Builder mcpWebClientBuilder(OAuth2AuthorizedClientManager clientManager) {
        return WebClient.builder().filter(
                new McpOAuth2AuthorizationCodeExchangeFilterFunction(
                        clientManager,
                        "authserver"
                )
        );
    }
}
```

--------------------------------

### Configure API Key Authentication

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/00-START-HERE.md

Set up API key authentication for MCP services using McpApiKeyConfigurer. Ensure an apiKeyRepository is provided.

```java
@Bean
SecurityFilterChain filterChain(HttpSecurity http) {
    return http
        .with(McpApiKeyConfigurer.mcpServerApiKey(), apiKey ->
            apiKey.apiKeyRepository(apiKeyRepository())
        )
        .build();
}
```

--------------------------------

### Handle OAuth2AuthenticationException in Spring Security

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/errors.md

This example shows how to catch OAuth2AuthenticationException and specifically check for the 'insufficient_scope' error code. It logs a message and returns a 401 status.

```java
import org.springframework.http.ResponseEntity;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.web.bind.annotation.ExceptionHandler;

// ... other imports and class annotations

@ExceptionHandler(OAuth2AuthenticationException.class)
ResponseEntity<String> handleOAuth2Error(OAuth2AuthenticationException e) {
    if (e.getError() != null && "insufficient_scope".equals(e.getError().getErrorCode())) {
        // Scope step-up available
        logger.info("Additional scopes required");
    }
    return ResponseEntity.status(401).build();
}
```

--------------------------------

### Launch MCP Inspector

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Launches the MCP Inspector tool, which provides an interactive interface for exploring and testing MCP servers. This tool requires Node.js and npm.

```shell
npx @modelcontextprotocol/inspector@latest
```

--------------------------------

### MCP Server OAuth2 Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Configure OAuth2 and MCP server details for resource server setup. Ensure the JWT issuer URI is provided for authentication.

```properties
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9000
spring.ai.mcp.server.name=my-mcp-server
spring.ai.mcp.server.protocol=STREAMABLE
```

--------------------------------

### Complete MCP Server OAuth2 Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-server-oauth2-configurer.md

Demonstrates a complete security configuration for an MCP server using OAuth2. This snippet shows how to set up authorization rules, configure the OAuth2 resource server, and customize session binding.

```java
@Configuration
@EnableWebSecurity
public class McpServerConfiguration {

    @Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}")
    private String issuerUrl;

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .with(McpServerOAuth2Configurer.mcpServerOAuth2(), mcpAuthorization -> {
                mcpAuthorization
                    .authorizationServer(issuerUrl)
                    .resourceName("My MCP Server")
                    .resourcePath("http://localhost:8090/mcp")
                    .validateAudienceClaim(true)
                    .sessionBinding(Customizer.withDefaults());
            })
            .build();
    }
}
```

--------------------------------

### Get Scope Method

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

Extracts the `scope` parameter from the challenge, used for scope step-up to determine required scopes. Returns a space-separated scope list or null.

```java
public String getScope()
```

--------------------------------

### McpClientOAuth2Configurer Constructor

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-client-oauth2-configurer.md

Creates a new instance of the McpClientOAuth2Configurer. It automatically detects the application context (Servlet/Spring Boot) to enable specific features.

```java
public McpClientOAuth2Configurer()
```

--------------------------------

### OAuth2AuthorizationCodeSyncHttpRequestCustomizer Constructor

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/http-request-customizers.md

Creates a customizer that uses a single fixed client registration for all requests.

```APIDOC
## OAuth2AuthorizationCodeSyncHttpRequestCustomizer Constructor

### Signature
```java
public OAuth2AuthorizationCodeSyncHttpRequestCustomizer(OAuth2AuthorizedClientManager clientManager, ClientRegistrationRepository registrationRepository, String registrationId)
```

### Parameters
#### Path Parameters
- **clientManager** (OAuth2AuthorizedClientManager) - Required - Manager for obtaining authorized clients
- **registrationRepository** (ClientRegistrationRepository) - Required - Repository of client registrations
- **registrationId** (String) - Required - ID of the client registration to use

### Description
Creates a customizer that uses a single fixed client registration for all requests.

### Example
```java
var customizer = new OAuth2AuthorizationCodeSyncHttpRequestCustomizer(
    clientManager,
    registrationRepository,
    "my-client"
);
```
```

--------------------------------

### Custom DatabaseApiKeyEntityRepository Implementation Pattern

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/api-key-entity-repository.md

Illustrates a pattern for implementing a custom ApiKeyEntityRepository using a database DAO and PasswordEncoder.

```java
public class DatabaseApiKeyEntityRepository implements ApiKeyEntityRepository<ApiKeyEntity> {
    
    private final ApiKeyDao dao;
    private final PasswordEncoder passwordEncoder;
    
    public DatabaseApiKeyEntityRepository(ApiKeyDao dao, PasswordEncoder passwordEncoder) {
        this.dao = dao;
        this.passwordEncoder = passwordEncoder;
    }
    
    @Override
    public Optional<ApiKeyEntity> findByApiKeyId(String id) {
        return dao.findById(id);
    }
}

```

--------------------------------

### Set API Key Repository

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-api-key-configurer.md

Configures the repository for API key entities, which is required for storing and retrieving API keys. The example uses an in-memory repository for development purposes.

```java
apiKey.apiKeyRepository(new InMemoryApiKeyEntityRepository<>( 
    List.of( 
        ApiKeyEntityImpl.builder() 
            .id("api01") 
            .name("test-key") 
            .secret("my-secret-key") 
            .build() 
    ) 
));
```

--------------------------------

### Basic MCP API Key Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-api-key-configurer.md

Configure the McpApiKeyConfigurer with a repository and a custom header name. This is useful for standard API key authentication.

```java
@Configuration
@EnableWebSecurity
public class McpServerConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) {
        return http
            .authorizeHttpRequests(authz -> authz.anyRequest().authenticated())
            .with(McpApiKeyConfigurer.mcpServerApiKey(), apiKey -> {
                apiKey.apiKeyRepository(apiKeyRepository())
                      .headerName("X-API-Key");
            })
            .build();
    }

    private ApiKeyEntityRepository<ApiKeyEntityImpl> apiKeyRepository() {
        var key1 = ApiKeyEntityImpl.builder()
            .id("api01")
            .name("Production Key")
            .secret("prod-secret-value")
            .build();
        var key2 = ApiKeyEntityImpl.builder()
            .id("api02")
            .name("Development Key")
            .secret("dev-secret-value")
            .build();
        return new InMemoryApiKeyEntityRepository<>(List.of(key1, key2));
    }
}
```

--------------------------------

### Configure OAuth2 Resource Server with McpServerOAuth2Configurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Use McpServerOAuth2Configurer for fluent configuration of an OAuth2 resource server. This setup is suitable for securing APIs that require OAuth2 bearer tokens.

```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) {
    return http
        .with(McpServerOAuth2Configurer.mcpServerOAuth2(), mcpAuth -> {
            mcpAuth.authorizationServer("http://localhost:9000")
                   .resourceName("My MCP Server")
                   .resourcePath("http://localhost:8090/mcp")
                   .validateAudienceClaim(true)
                   .sessionBinding(Customizer.withDefaults());
        })
        .build();
}
```

--------------------------------

### API Key Authentication Flow

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authentication-providers.md

Illustrates the sequence of operations for API Key authentication, from receiving the request to setting the authentication in the Security Context.

```text
HTTP Request with "X-API-Key: id.secret" header
    ↓
ApiKeyAuthenticationConverter.convert()
    ↓ (returns unauthenticated token)
ApiKeyAuthenticationProvider.authenticate()
    ↓ (verifies against repository)
ApiKeyAuthenticationToken (authenticated)
    ↓
SecurityContextHolder.getContext().setAuthentication()
```

--------------------------------

### Enable Authorization Server Auto-Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authorization-server-configurer.md

Set this property to true to enable the automatic registration of the authorization server configurer. Ensure default client properties are also configured.

```properties
spring.ai.mcp.authorizationserver.dynamic-client-registration.enabled=true

spring.security.oauth2.authorizationserver.client.default-client.registration.client-id=default-client
spring.security.oauth2.authorizationserver.client.default-client.registration.client-secret={noop}secret
spring.security.oauth2.authorizationserver.client.default-client.registration.authorization-grant-types=authorization_code,client_credentials
spring.security.oauth2.authorizationserver.client.default-client.registration.redirect-uris=http://localhost:8080/authorize/oauth2/code/authserver
```

--------------------------------

### Manual Security Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/README.md

Use this pattern for custom security configurations, such as setting up an OAuth2 authorization server.

```java
@Configuration
@EnableWebSecurity
public class MySecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .with(McpServerOAuth2Configurer.mcpServerOAuth2(), mcp -> {
                mcp.authorizationServer("http://auth.example.com");
            })
            .build();
    }
}
```

--------------------------------

### Enable MCP Server in application.properties

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Configure the MCP server name and protocol in your application properties. Supported protocols include STREAMABLE and STATELESS.

```properties
spring.ai.mcp.server.name=my-cool-mcp-server
# Supported protocols: STREAMABLE, STATELESS
spring.ai.mcp.server.protocol=STREAMABLE
```

--------------------------------

### DefaultClientIdMetadataDocumentResolver.resolve

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/metadata-services.md

Resolves client metadata documents by fetching them via HTTP GET from a given URL. It validates the URL, fetches the JSON response, parses it, validates required fields, and caches the result.

```APIDOC
## resolve(String clientIdUrl)

### Description
Fetches and parses client metadata from a specified URL.

### Method
GET

### Endpoint
```
{clientIdUrl}
```

### Parameters
#### Path Parameters
- **clientIdUrl** (String) - Required - The URL to fetch the client metadata document from.

### Response
#### Success Response (200)
- **metadata** (OAuth2ClientMetadata) - The parsed and validated client metadata.

### Response Example
```json
{
  "client_id": "example-client-id",
  "redirect_uris": ["https://example.com/callback"]
}
```
```

--------------------------------

### OAuth2AuthorizationCodeSyncHttpRequestCustomizer Constructor

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/http-request-customizers.md

Constructs an OAuth2AuthorizationCodeSyncHttpRequestCustomizer with a specific client manager, registration repository, and registration ID.

```java
public OAuth2AuthorizationCodeSyncHttpRequestCustomizer(
    OAuth2AuthorizedClientManager clientManager,
    ClientRegistrationRepository registrationRepository,
    String registrationId)
```

--------------------------------

### Manual AuthenticationMcpTransportContextProvider and Request Customizer Configuration

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Configure an AuthenticationMcpTransportContextProvider and an OAuth2AuthorizationCodeSyncHttpRequestCustomizer when not using Boot auto-configuration for HttpClient transports. This provides user-level tokens.

```java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import com.mcp.security.client.McpSyncClientCustomizer;
import com.mcp.security.client.McpSyncHttpClientRequestCustomizer;
import com.mcp.security.oauth2.client.http.OAuth2AuthorizationCodeSyncHttpRequestCustomizer;
import com.mcp.security.client.context.AuthenticationMcpTransportContextProvider;

@Configuration
class McpConfiguration {

    @Bean
    McpSyncClientCustomizer syncClientCustomizer() {
        return (name, syncSpec) ->
                syncSpec.transportContextProvider(
                        new AuthenticationMcpTransportContextProvider()
                );
    }

    @Bean
    McpSyncHttpClientRequestCustomizer requestCustomizer(
            OAuth2AuthorizedClientManager clientManager,
            ClientRegistrationRepository clientRegistrationRepository
    ) {
        return new OAuth2AuthorizationCodeSyncHttpRequestCustomizer(
                clientManager,
                clientRegistrationRepository,
                "authserver"
        );
    }

}
```

--------------------------------

### Caching API Key Entities

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/api-key-entity-repository.md

Implement caching for frequently used API key entities to reduce database load and improve response times. This example uses Spring's @Cacheable annotation.

```java
@Cacheable("apiKeyEntities")
public Optional<ApiKeyEntity> findByApiKeyId(String id) {
    return dao.findById(id);
}
```

--------------------------------

### Configure Security with McpClientOAuth2Configurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/README.md

Use McpClientOAuth2Configurer to set up OAuth2 client support and pre-register OAuth2 clients for specific MCP servers.

```java
@Configuration
@EnableWebSecurity
class SecurityConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
                .with(McpClientOAuth2Configurer.mcpClientOAuth2(), mcpOAuth2 -> {
                    // Pre-register an OAuth2 client for a specific MCP server
                    mcpOAuth2.registerMcpOAuth2Client("my-mcp-server", "http://localhost:8090/mcp");
                    // Optionally set the base URL for redirect URIs
                    // mcpOAuth2.baseUrl("http://localhost:8080");
                })
                .build();
    }

}
```

--------------------------------

### OAuth2HybridSyncHttpRequestCustomizer Constructor

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/http-request-customizers.md

Demonstrates the constructor for OAuth2HybridSyncHttpRequestCustomizer, which requires an OAuth2AuthorizedClientManager, ClientRegistrationRepository, and a registrationId.

```java
public OAuth2HybridSyncHttpRequestCustomizer(
    OAuth2AuthorizedClientManager clientManager,
    ClientRegistrationRepository registrationRepository,
    String registrationId)
```

--------------------------------

### Custom Security Filter Chain

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/configuration.md

Create a custom SecurityFilterChain for advanced security scenarios. This example disables CSRF, permits public access to /public/**, and requires authentication for all other requests, integrating MCP Server OAuth2.

```java
@Configuration
@EnableWebSecurity
public class CustomSecurityConfiguration {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(CsrfConfigurer::disable)
            .authorizeHttpRequests(auth -> {
                auth.requestMatchers("/public/**").permitAll();
                auth.anyRequest().authenticated();
            })
            .with(McpServerOAuth2Configurer.mcpServerOAuth2(), mcpAuth -> {
                mcpAuth.authorizationServer("http://localhost:9000");
            })
            .build();
    }
}
```

--------------------------------

### sessionBinding(Customizer<SessionBindingConfigurer> sessionBindingCustomizer)

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/mcp-api-key-configurer.md

Enables and configures MCP session binding for API key authentication.

```APIDOC
## sessionBinding(Customizer<SessionBindingConfigurer> sessionBindingCustomizer)

### Description
Enables and configures MCP session binding for API key authentication. When enabled, ensures that a session created with one API key can only be used with that same API key, implementing security best practices. The session is bound to the principal's name (typically the API key entity's ID).

### Method
`public McpApiKeyConfigurer sessionBinding(Customizer<SessionBindingConfigurer> sessionBindingCustomizer)`

### Parameters
#### Request Body
- **sessionBindingCustomizer** (Customizer<SessionBindingConfigurer>) - Required - Customizer for session binding configuration

### Returns
`McpApiKeyConfigurer` — this for chaining

### Example
```java
apiKey.sessionBinding(Customizer.withDefaults());
```
```

--------------------------------

### Call Protected MCP Server Endpoint

Source: https://github.com/spring-ai-community/mcp-security/blob/main/samples/README.md

Makes a POST request to the MCP server endpoint using an obtained OAuth 2.0 access token. The token must be included in the Authorization header. This example demonstrates sending an initialization request.

```shell
export OAUTH2_TOKEN=<your token goes here>

curl -XPOST "http://localhost:8090/mcp" \
   -d '{"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"curl-client","version":"0.19.0"}},"jsonrpc":"2.0","id":0}' \
   --header "Accept: application/json" \
   --header "Accept: text/event-stream" \
   --header "Content-type: application/json" \
   --header "Authorization: Bearer $OAUTH2_TOKEN"
```

--------------------------------

### Static Factory Method for McpAuthorizationServerConfigurer

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/api-reference/authorization-server-configurer.md

Factory method to create a new authorization server configurer instance. Used in security filter chain configuration.

```java
public static McpAuthorizationServerConfigurer mcpAuthorizationServer()
```

--------------------------------

### DelegatingRegisteredClientRepository Constructor

Source: https://github.com/spring-ai-community/mcp-security/blob/main/_autodocs/types.md

Creates a composite repository that delegates client lookups to multiple repositories. Useful for supporting both pre-registered clients and CIMD/DCR clients simultaneously.

```java
public class DelegatingRegisteredClientRepository implements RegisteredClientRepository
```
Tokens:
Raw