Interface McpHandlerInterceptor

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@ThreadSafe @FunctionalInterface public interface McpHandlerInterceptor
Thread-safe server-level interceptor for every application-owned MCP handler invocation.

Soklet invokes the configured interceptor for tool calls, prompt gets, resource reads, argument completion, and custom resource-list handling, including handlers discovered from annotations. Framework-owned discovery and static catalog generation do not invoke application handlers and therefore do not traverse this hook.

Interception occurs after admission, rate limiting, handler-queue admission, and handler-slot acquisition, but before complete application-input validation and handler invocation. Applications that need an interceptor chain compose it behind this one hook and own its ordering.

An interceptor may invoke the continuation and transform its result, or may short-circuit by returning a method-compatible result without invoking it. Either result still traverses Soklet's applicable result validation, tool-output sanitization, output-schema validation, and response generation. Argument-completion invocations require an McpArgumentCompletionResult; a result for another MCP operation is rejected even when returned by an interceptor. Custom Skills-list handlers require a McpSkillPage; automatic skills/list and skills/get responses remain framework-owned and are not intercepted. Skills-file reads are intercepted only after fresh owner authorization and canonical resource-result construction. Their canonical URI, MIME type, contents and representation must remain unchanged; result metadata may be added, and freshness may be shortened but not widened beyond the shared-file cache policy and applicable security clamps. A null return or an interceptor-authored exception fails closed without exposing exception-derived data. The continuation exposes a handler's intentional McpJsonRpcException as the original object. An interceptor may inspect and rethrow that same object to preserve the handler error, or return a method-compatible recovery result. Replacing or wrapping the exception, or throwing one retained from an earlier invocation, is an interception failure and does not expose its error to the client.

Implementations must be safe for concurrent invocation. Each supplied continuation remains synchronous, one-shot, and bound to the invoking thread as documented by McpHandlerContinuation. The feature lookup is the exact instance supplied to the downstream handler; its lookup and feature-value contracts remain those documented by McpInvocationFeatures.

Author:
Mark Allen