Advanced9 min
MCP Interceptors
Interceptors wrap MCP tool calls in an onion pattern — inject context, add auth headers, implement retries, gate access, and return Commands for state updates. The middleware layer for MCP.
Quick Reference
- →Interceptors are async functions that wrap MCP tool execution — like middleware for tool calls
- →Access request.runtime for state, context, store — same as ToolRuntime
- →Onion pattern: multiple interceptors execute in defined order, each wrapping the next
- →Can modify requests (add headers), short-circuit (return early), or retry on failure
- →Can return Command objects for state updates and graph flow control
- →Composable: auth interceptor + logging interceptor + retry interceptor stack cleanly
What Are Interceptors?
Request → Auth → Retry → Logging → Tool Call → Logging → Retry → Auth → Response
MCP interceptors wrap tool calls in an onion pattern — each interceptor receives the request, can modify it, pass it to the next interceptor (or the actual tool), and then process the response. They're the equivalent of middleware for MCP tool calls, giving you control over authentication, logging, retries, and access control without modifying the MCP server.
| Use Case | What the Interceptor Does |
|---|---|
| Authentication | Inject user-specific OAuth tokens into MCP server requests |
| Logging | Record every tool call with timing, args, and results to LangSmith |
| Retry | Retry failed MCP calls with exponential backoff |
| Access control | Block tool calls based on user permissions |
| Context injection | Add user_id, session_id, or other context to tool args |
| Rate limiting | Throttle calls to external MCP servers |