# Security Best Practices for Using embabel-agent: A Developer’s Guide to Production Safety

> Learn embabel-agent security best practices. Secure your production apps with JWT authentication, method authorization, and enhanced observability for input validation and audit logging.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: best-practices
- Published: 2026-08-14

---

**TLDR:** Secure embabel-agent by leveraging its Spring Boot security auto-configuration for JWT-based MCP server authentication, enforcing method-level authorization with `@PreAuthorize`, and extending the `TrackedAspect` observability layer for input validation and audit logging.

The embabel-agent framework provides a Spring Boot-based foundation for building AI agent applications with modular auto-configuration. Understanding the **security best practices for using embabel-agent** is critical to protecting both the Model Context Protocol (MCP) server endpoints and the tool execution pipelines in production environments.

## Core Security Architecture

The embabel-agent security model operates on two distinct layers that developers must configure correctly to ensure comprehensive protection.

### Infrastructure-Level Protection

The MCP server—the remote tool-execution endpoint—is secured by the `AgentMcpServerAutoConfiguration` class located in [`embabel-agent-autoconfigure/embabel-agent-mcpserver-security-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/security/AgentMcpServerAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-mcpserver-security-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/security/AgentMcpServerAutoConfiguration.java). This configuration imports `SecureAgentToolConfiguration` and `SecureAgentSecurityConfiguration`, which wire essential Spring Security components including a `JwtAuthenticationConverter`, a `SecurityFilterChain`, and a method-security expression handler. These beans enforce stateless authentication and coarse-grained access control at the transport layer.

### Application-Level Controls

All agent-exposed services are wrapped by the **Observed Aspect** (`TrackedAspect`) found in [`embabel-agent-observability/src/main/java/com/embabel/agent/observability/tracing/TrackedAspect.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-observability/src/main/java/com/embabel/agent/observability/tracing/TrackedAspect.java). Because this aspect executes before and after each public method invocation, it serves as an interception point for audit logging, rate-limiting, and pre-execution validation. The framework automatically enables method-level security annotations such as `@PreAuthorize` when the security auto-configuration classes are present on the classpath.

## Critical Security Best Practices

Implementing robust security requires addressing credentials, transport, authorization, and runtime validation.

### Never Hard-Code Secrets

Store API keys, JWT signing secrets, and database passwords in environment variables or dedicated secret managers. Hard-coded credentials in [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml) or source code frequently leak into version control and logs.

```properties

# application.yml (use environment variables for actual values)

spring.security.oauth2.resourceserver.jwt.issuer-uri=${JWT_ISSUER_URI}
spring.security.oauth2.resourceserver.jwt.audiences=${JWT_AUDIENCES}

```

### Enforce HTTPS Everywhere

Deploy the embedded Tomcat server behind a TLS-terminating reverse proxy. For programmatic connector customization:

```java
@Bean
public TomcatServletWebServerFactory servletContainer() {
    TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
    factory.addConnectorCustomizers(connector -> connector.setSecure(true));
    return factory;
}

```

### Implement JWT and OAuth2 for MCP Endpoints

The auto-configured `JwtAuthenticationConverter` validates signed tokens and populates the Spring Security `Authentication` object. Explicitly configure the security filter chain to protect MCP routes:

```java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class AgentSecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(authz -> authz
                .requestMatchers("/mcp/**").authenticated()
                .anyRequest().permitAll())
            .oauth2ResourceServer(oauth -> oauth.jwt());
        return http.build();
    }
}

```

### Apply Method-Level Authorization

Annotate sensitive tool-invocation methods with `@PreAuthorize` to enforce least-privilege access. This complements the coarse-grained HTTP security with fine-grained function-level controls:

```java
@PreAuthorize("hasAuthority('tool:run')")
public String executeTool(ToolRequest request) {
    // tool logic
    return "success";
}

```

### Validate All Inbound Data

Extend the `TrackedAspect` to perform schema validation or sanitization before the agent core processes a request. The aspect’s interception mechanism provides a single chokepoint for rejecting malformed payloads:

```java
@Around("@annotation(com.embabel.agent.observability.annotation.Tracked)")
public Object validateAndProceed(ProceedingJoinPoint pjp) throws Throwable {
    Object[] args = pjp.getArgs();
    // Inspect and validate args, throw SecurityException if invalid
    return pjp.proceed();
}

```

### Configure CSRF Protection

Maintain Spring Security’s default CSRF filter enabled for state-changing endpoints. Disable CSRF protection **only** when exposing a pure REST API protected exclusively by JWT bearer tokens:

```java
// Only disable for JWT-only REST APIs
http.csrf(csrf -> csrf.disable());

```

### Leverage Observability for Security Monitoring

Integrate `MicrometerAgentInstrumentation` to emit metrics on authentication failures, rejected payloads, and unusual access patterns. Real-time dashboards enable rapid incident detection:

```java
@Bean
public MicrometerAgentInstrumentation micrometerInstrumentation(MeterRegistry registry) {
    return new MicrometerAgentInstrumentation(registry);
}

```

### Maintain Dependency Hygiene

Regularly audit the Spring Boot, Spring Security, Tomcat, and cryptographic libraries for CVEs. Use Maven’s versions plugin to identify outdated components:

```bash
mvn dependency:tree
mvn versions:use-latest-releases

```

## Practical Implementation Examples

The following examples demonstrate common security configurations for production embabel-agent deployments.

### Enabling JWT Protection for the MCP Server

Create a configuration class that customizes the `SecurityFilterChain` while retaining the auto-configured JWT converter provided by `AgentMcpServerAutoConfiguration`:

```java
package com.example.agent;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableMethodSecurity // Activates @PreAuthorize annotations
public class AgentSecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        // Require authentication for all "/mcp/**" endpoints
        http.authorizeHttpRequests(authz -> authz
                .requestMatchers("/mcp/**").authenticated()
                .anyRequest().permitAll())
            .oauth2ResourceServer(oauth -> oauth.jwt()); // Validates JWT tokens
        return http.build();
    }
}

```

The auto-configuration in `AgentMcpServerAutoConfiguration` imports the necessary security beans, so this class overrides defaults only when custom path restrictions are required.

### Restricting Tool Execution to Privileged Users

Combine the `@Tracked` annotation with `@PreAuthorize` to ensure observable, authorized access to sensitive tools:

```java
package com.example.agent.tools;

import org.springframework.security.access.prepost.PreAuthorize;
import com.embabel.agent.observability.annotation.Tracked;

@Component
public class SecureTool {

    @Tracked // Enables observability and validation hooks
    @PreAuthorize("hasAuthority('tool:run')")
    public String execute(String payload) {
        // Tool logic here
        return "Execution completed";
    }
}

```

The `TrackedAspect` logs the invocation metadata and can be extended to perform additional payload inspection before `execute()` runs.

## Key Security Files and Components

Understanding the location and purpose of these source files is essential for auditing and customizing the security posture:

- **[`embabel-agent-autoconfigure/embabel-agent-mcpserver-security-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/security/AgentMcpServerAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-mcpserver-security-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/security/AgentMcpServerAutoConfiguration.java)** – Imports `SecureAgentToolConfiguration` and `SecureAgentSecurityConfiguration`, wiring the `SecurityFilterChain`, `JwtAuthenticationConverter`, and method-security handlers.
- **[`embabel-agent-observability/src/main/java/com/embabel/agent/observability/tracing/TrackedAspect.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-observability/src/main/java/com/embabel/agent/observability/tracing/TrackedAspect.java)** – AOP aspect that intercepts public method calls for audit logging and pre-validation hooks.
- **[`MicrometerAgentInstrumentation.java`](https://github.com/embabel/embabel-agent/blob/main/MicrometerAgentInstrumentation.java)** (observability/metrics) – Emits Micrometer metrics for security events such as authentication failures.
- **[`AgentMcpServerSecurityAutoConfigurationTest.java`](https://github.com/embabel/embabel-agent/blob/main/AgentMcpServerSecurityAutoConfigurationTest.java)** (test) – Validates that the auto-configuration correctly instantiates the expected Spring Security beans, serving as a reference for expected behavior.

## Summary

- **Leverage auto-configuration**: Rely on `AgentMcpServerAutoConfiguration` to wire JWT and Spring Security infrastructure for MCP endpoints.
- **Enforce least privilege**: Use `@PreAuthorize` annotations on tool methods to restrict execution to authorized principals.
- **Validate inputs**: Extend `TrackedAspect` to inspect and sanitize payloads before they reach the agent core.
- **Protect secrets**: Externalize all credentials to environment variables or secret management systems.
- **Monitor continuously**: Use `MicrometerAgentInstrumentation` and the `TrackedAspect` audit trail to detect anomalous access patterns.

## Frequently Asked Questions

### How does embabel-agent handle authentication for MCP server endpoints?

The framework uses `AgentMcpServerAutoConfiguration` to import `SecureAgentSecurityConfiguration`, which configures a Spring Security `SecurityFilterChain` and a `JwtAuthenticationConverter`. This setup validates JWT tokens on incoming requests to `/mcp/**` paths and populates the security context with authentication details derived from the token claims.

### Can I use method-level security annotations like `@PreAuthorize` with embabel-agent?

Yes. When the security auto-configuration is present, Spring Security’s method security is automatically enabled. You can annotate tool methods with `@PreAuthorize("hasAuthority('tool:run')")` to enforce fine-grained authorization decisions based on the authenticated user’s authorities.

### What is the purpose of the `TrackedAspect` in security contexts?

`TrackedAspect` provides an AOP interception point around methods annotated with `@Tracked`. It records request and response metadata for audit trails and offers a configurable hook to perform input validation, rate limiting, or additional security checks before method execution proceeds, as implemented in [`embabel-agent-observability/src/main/java/com/embabel/agent/observability/tracing/TrackedAspect.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-observability/src/main/java/com/embabel/agent/observability/tracing/TrackedAspect.java).

### How should I manage JWT secrets in an embabel-agent application?

Never commit JWT signing keys or issuer URIs to version control. Configure these values via environment variables injected into [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml) (e.g., `${JWT_ISSUER_URI}`), or use a dedicated secret manager like HashiCorp Vault or AWS Secrets Manager integration with Spring Cloud.