Skip to main content
View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/mcp_use/middleware/middleware.py
Core middleware system for MCP requests. This module provides a robust and extensible middleware architecture:
  • A typed MiddlewareContext to carry request data.
  • A Middleware base class with a dispatcher that routes to strongly-typed hooks.
  • A MiddlewareManager to build and execute the processing chain.
  • A CallbackClientSession that acts as an adapter, creating the initial context without requiring changes to upstream callers like HttpConnector.

​
CallbackClientSession

from mcp_use.middleware.middleware import CallbackClientSession

​
method init

Parameters
​
client_session
mcp.client.session.ClientSession
required
MCP session instance
​
connector_id
str
required
Connector instance
​
middleware_manager
mcp_use.middleware.middleware.MiddlewareManager
required
Middleware instance
Signature
def __init__(client_session: mcp.client.session.ClientSession, connector_id: str, middleware_manager: mcp_use.middleware.middleware.MiddlewareManager):

​
method call_tool

Parameters
​
name
str
required
Name identifier
​
arguments
dict[str, Any]
required
Dictionary of key-value pairs
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.CallToolResult
Signature
def call_tool(name: str, arguments: dict[str, Any], args, kwargs):

​
method get_prompt

Parameters
​
name
str
required
Name identifier
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.GetPromptResult
Signature
def get_prompt(name: str, args, kwargs):

​
method initialize

Parameters
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.InitializeResult
Signature
def initialize(args, kwargs):

​
method list_prompts

Parameters
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.ListPromptsResult
Signature
def list_prompts(args, kwargs):

​
method list_resources

Parameters
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.ListResourcesResult
Signature
def list_resources(args, kwargs):

​
method list_tools

Parameters
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.ListToolsResult
Signature
def list_tools(args, kwargs):

​
method read_resource

Parameters
​
uri
str
required
String value
​
args
required
Parameter value
​
kwargs
required
Parameter value
Returns
​
returns
mcp.types.ReadResourceResult
Signature
def read_resource(uri: str, args, kwargs):

​
MCPResponseContext

from mcp_use.middleware.middleware import MCPResponseContext

Attributes
​
request_id
str
required
String value
​
result
Any
required
Parameter value
​
error
Exception | None
required
Parameter value
​
duration
float
required
Parameter value
​
metadata
dict[str, Any]
required
Dictionary of key-value pairs
​
jsonrpc_response
mcp.types.JSONRPCResponse | None
required
Parameter value

​
method init

Parameters
​
request_id
str
required
String value
​
result
Any
required
Parameter value
​
error
Exception | None
required
Parameter value
​
duration
float
required
Parameter value
​
metadata
dict[str, Any]
required
Dictionary of key-value pairs
​
jsonrpc_response
mcp.types.JSONRPCResponse | None
default:"None"
Parameter value
Signature
def __init__(request_id: str, result: Any, error: Exception | None, duration: float, metadata: dict[str, Any], jsonrpc_response: mcp.types.JSONRPCResponse | None = None):

​
Middleware

from mcp_use.middleware.middleware import Middleware

​
method call

Main entry point that orchestrates the chainParameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
Any
Signature
def __call__(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_call_tool

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.CallToolResult
Signature
def on_call_tool(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_get_prompt

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.GetPromptResult
Signature
def on_get_prompt(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_initialize

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.InitializeResult
Signature
def on_initialize(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_list_prompts

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.ListPromptsResult
Signature
def on_list_prompts(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_list_resources

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.ListResourcesResult
Signature
def on_list_resources(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_list_tools

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.ListToolsResult
Signature
def on_list_tools(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_read_resource

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
mcp.types.ReadResourceResult
Signature
def on_read_resource(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
method on_request

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
call_next
mcp_use.middleware.middleware.NextFunctionT
required
Parameter value
Returns
​
returns
Any
Signature
def on_request(
context: mcp_use.middleware.middleware.MiddlewareContext,
    call_next: mcp_use.middleware.middleware.NextFunctionT
):

​
MiddlewareContext

from mcp_use.middleware.middleware import MiddlewareContext

Attributes
​
id
str
required
String value
​
method
str
required
String value
​
params
mcp_use.middleware.middleware.T
required
Parameter value
​
connection_id
str
required
String value
​
timestamp
float
required
Parameter value
​
metadata
dict[str, Any]
required
Dictionary of key-value pairs

​
method init

Parameters
​
id
str
required
String value
​
method
str
required
String value
​
params
mcp_use.middleware.middleware.T
required
Parameter value
​
connection_id
str
required
String value
​
timestamp
float
required
Parameter value
​
metadata
dict[str, Any]
default:"<factory>"
Dictionary of key-value pairs
Signature
def __init__(id: str, method: str, params: mcp_use.middleware.middleware.T, connection_id: str, timestamp: float, metadata: dict[str, Any] = <factory>):

​
MiddlewareManager

from mcp_use.middleware.middleware import MiddlewareManager

​
method init

Signature
def __init__():

​
method add_middleware

Add a middleware callback.Parameters
​
callback
mcp_use.middleware.middleware.Middleware
required
Callback function
Signature
def add_middleware(callback: mcp_use.middleware.middleware.Middleware):

​
method process_request

Runs the full middleware chain, captures timing and errors, and returns a structured MCPResponseContext.Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
​
original_call
Callable
required
Parameter value
Returns
​
returns
mcp_use.middleware.middleware.MCPResponseContext
Signature
def process_request(
context: mcp_use.middleware.middleware.MiddlewareContext,
    original_call: Callable
):

​
NextFunctionT

from mcp_use.middleware.middleware import NextFunctionT

​
method init

Parameters
​
args
required
Parameter value
​
kwargs
required
Parameter value
Signature
def __init__(args, kwargs):

​
method call

Parameters
​
context
mcp_use.middleware.middleware.MiddlewareContext
required
Parameter value
Returns
​
returns
mcp_use.middleware.middleware.R
Signature
def __call__(context: mcp_use.middleware.middleware.MiddlewareContext):
⌘I