Need Way To Trigger 401 Response From Tools, Middleware, or Wrapper?

[Norcim133]

Enhancement

For situations where the Server needs to try and access protected resources with access tokens passed by client, we need a way to propagate the 401s from API calls from inside tools.

I tried to do it in my context wrapper and in a middleware but I think the respones are happening in a different layer.

Might exist already but I could find this in the docs.

[marvin-context-protocol]

Found 1 possible duplicate issue:

1. Question about how to handling auth error in openapi integration and proxy server #1082: Question about how to handling auth error in openapi integration and proxy server

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

[Norcim133]

The reason this is important is I suspect the actual main flow people want to use is this below.

It doesn't show the step but one needs a way to handle rejection by the 3rd Party Server to signal refresh and such.

[jlowin]

At this time, the server is either entirely protected, or not protected at all. We don't recognize HTTP errors coming from inside the server. I think its a good idea to bubble up http errors but it will take some special handling because not every server is http-deployed so I want to make sure we dont inadvertently introduce bad outcomes. Furthermore the MCP layer (the SDK) is going to intercept most errors and convert them into JSONRPC so I'm not sure how much opportunity we have to raise proper HTTP errors here.

/marvin can you research what opportunities we have, if any, to raise e.g. a 401 from inside a tool and have confidence it will actually be captured and returned? or does this require new HTTP middleware in say http.py? Don't open a PR, just return a concise report on how this could work.

[marvin-context-protocol]

Claude finished @jlowin's task —— View job

---

Research: Bubbling 401 Errors from Tools to HTTP Response

I've completed a thorough analysis of how FastMCP could support bubbling HTTP 401 errors from tools to the HTTP response layer. Here are my findings:

Current Error Flow

The Challenge: FastMCP currently follows this error conversion path:

1. Tool/middleware exceptions → ErrorHandlingMiddleware → McpError → JSONRPC response → HTTP 200 wrapper

This means all HTTP status codes (401, 404, 500, etc.) are lost and become JSONRPC errors wrapped in HTTP 200 responses.

Key Findings

❌ No Current Support

• No mechanism exists to preserve HTTP status codes through the MCP protocol layer
• All errors are converted to JSONRPC responses per MCP specification
• The StreamableHttpTransport always wraps JSONRPC in HTTP 200 responses

⚠️ Architecture Limitation

• MCP (Model Context Protocol) is fundamentally JSONRPC-based, not HTTP-aware
• The underlying mcp library converts all exceptions to JSONRPC errors
• Non-HTTP deployments (stdio, SSE) wouldn't understand HTTP status codes

Potential Solutions

Option 1: HTTP-Aware Exception Types (Recommended)

class HttpStatusError(Exception):
    def __init__(self, status_code: int, message: str, headers: dict = None):
        self.status_code = status_code
        self.headers = headers or {}
        super().__init__(message)

Option 2: Enhanced Error Middleware

• Detect HTTP-aware exceptions in ErrorHandlingMiddleware
• Preserve status codes in MCP error metadata
• Requires transport-layer cooperation

Option 3: Transport-Level Handler

• Modify StreamableHttpTransport to intercept MCP errors with HTTP metadata
• Convert back to proper HTTP responses before sending
• Only works for HTTP deployments

Implementation Approach

The cleanest solution would require new HTTP middleware in src/fastmcp/server/http.py:

1. Before MCP processing: Check if HTTP context is available
2. After MCP error: Examine error metadata for HTTP status codes
3. Response override: Return proper HTTP status instead of HTTP 200 + JSONRPC error

This would need careful handling to:

• Only apply to HTTP transports (not stdio/SSE)
• Maintain MCP compatibility for non-HTTP clients
• Preserve error details in both HTTP and MCP formats

Recommendation

This feature is technically feasible but requires significant architectural consideration. The best approach would be adding HTTP-aware error handling as an optional HTTP-only feature that doesn't break MCP compatibility for other transport types.

---

Job Run | Branch

[jlowin]

/marvin I'm not clear on whether there is even an opportunity for us to surface a 401 at all once the request has entered the MCP server (and consequently the JSONRPC spec). If we don't return JSONRPC, will it break the low-level server's expectations and crash?

[marvin-context-protocol]

Claude finished @jlowin's task —— View job

---

Analyzing MCP/JSONRPC Constraints for HTTP 401 Responses

Todo List:

• Examine FastMCP HTTP server architecture
• Analyze MCP/JSONRPC protocol expectations
• Test what happens with non-JSONRPC responses
• Determine if there are safe opportunities for HTTP status codes
• Provide technical assessment and recommendations

---

Key Findings

❌ No viable path once in MCP/JSONRPC layer

Once a request has entered the MCP server and is being processed as JSONRPC, returning non-JSONRPC responses will break the low-level server's expectations. Here's why:

Architecture Analysis

The Constraint: MCP protocol is fundamentally JSONRPC-based. From my analysis of the codebase:

1. StreamableHTTPSessionManager (in the underlying mcp library) expects all responses to be JSONRPC
2. Error handling middleware converts all exceptions to McpError → JSONRPC responses
3. All MCP transports (stdio, SSE, streamable-http) wrap everything in JSONRPC

The Problem: Tools/middleware that throw exceptions get converted to JSONRPC errors in ErrorHandlingMiddleware:110-119. There's no mechanism to preserve HTTP status codes through this conversion.

What Actually Works

HTTP status codes do work in FastMCP, but only outside the MCP protocol layer:

# This works - in component management routes (contrib/component_manager.py:101)
raise StarletteHTTPException(status_code=404, detail="Not found")

# This gets converted to JSONRPC - in tools/middleware
raise ValueError("Some error")  # → McpError → JSONRPC wrapped in HTTP 200

Critical Question Answered

"If we don't return JSONRPC, will it break the low-level server's expectations and crash?"

Yes, absolutely. The StreamableHTTPSessionManager expects JSONRPC responses. Returning raw HTTP 401 responses would:

• Break the MCP client protocol expectations
• Crash non-HTTP transports (stdio, SSE)
• Violate the JSONRPC specification that MCP is built on

Limited Solutions

Option 1: HTTP-Only Routes (What component manager does)

• Add custom HTTP routes outside the MCP protocol
• These can use proper HTTP status codes
• Only works for HTTP transport, breaks protocol consistency

Option 2: Enhanced Error Metadata (Theoretical)

• Preserve HTTP status info in McpError.data
• Require transport-specific interpretation
• Still wrapped in JSONRPC/HTTP 200, but metadata available

Recommendation

This feature is architecturally incompatible with MCP's JSONRPC foundation. The cleanest approach would be:

1. Accept the constraint: MCP protocol errors stay as JSONRPC errors
2. Implement auth at the transport layer: Handle 401s before requests enter the MCP server
3. Use custom HTTP routes: For any endpoints that need real HTTP status codes (like the component manager does)

The fundamental issue is that MCP is a protocol abstraction that intentionally hides HTTP details to work across multiple transports. Breaking that abstraction would compromise the protocol's transport independence.

---

Job Run | Branch

[jlowin]

Ok so based on all this I think we'll need to reuse patterns from e.g. #1113 to raise auth info to clients, and figure out if we have a clean way to re-raise HTTP exceptions maybe by monitoring JSONRCP error codes

[Norcim133]

Yeah, I reckon if it requires monitoring JSONRCP it's probably best left to the developer so you don't have maintain something hacky (e.g. I could pass the code to myself in a string and intercept that in the Client).

Totally brainstorming but what about:
a) Attaching a transport object to context and then firing the error from inside a middleware or tool using it?
b) Making a custome route with /mcp that overrides the app's main route (I can return 401 fine from custom routes)
c) Creating a new error (similar to Tool Error) and wrapping whole app in a listener... when New401Error emitted the wrap passes it as JSONObject/Response Code
d) Add a room for a callback in StaticTokenVerifier... I could trigger my downstream auth check there and, if rejected, StaticTokenVerifier would reject like it got a bad token

[Norcim133]

For my purpose I'm actually fine building my msgraph object and pinging MSFT in a custom route or an app wrapper prior to running FastMCP.

My only concerns then would be:
a) I need to be multi-user so need this to stay "inside" a unique Starlette/unvicorn async worker
b) I'd want to stay "standard" in all other respects for the MCP Client accessing it

[Norcim133]

How is this, @jlowin ?

I used the FastMCP integrations pattern.

Basically wrapped FastMCP inside a Starlette app + middleware that checks 3rd party auth, implicitly, before hitting mcp.

It works...

As in, I've done smoke tests and can:

1. Still get to fastmcp server via /mcp
2. I get a 401 when not auth
3. I can attach my object to state and get it in tools from get_http_request

Are there any 'gotchas' this would create for my multi-user setup (separate from the actual auth aspects)?

class InjectMicrosoftTokenMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        if request.url.path.startswith("/mcp"):
            ms_token = request.headers.get("X-Microsoft-Token")
            msgraph_object = {"tbd":"tbd"}
            
            if not ms_token:
                return JSONResponse(
                    {"error": "authentication_required"},
                    status_code=401
                )
            
            # Attach to request state
            request.state.graph = msgraph_object
        
        return await call_next(request)

if __name__ == "__main__":

    port = int(os.getenv("PORT", "8080"))
    # Create Starlette app with middleware
    app = Starlette(
        routes=[
            Mount("/", app=mcp_app),
        ],
        lifespan=mcp_app.lifespan,
    )
    app.add_middleware(InjectMicrosoftTokenMiddleware)
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=port)

Usage

@mcp.tool
async def echo_auth_info() -> dict:
    """Test tool to verify auth info is available"""
    headers = get_http_headers()
    request = get_http_request()
    user_id = getattr(request.state, 'user_id', 'not found')
    return {
        "all_headers": dict(headers),
        "ms_token_present": "X-Microsoft-Token".lower() in headers,
        "auth_header": headers.get("Authorization", "none"),
        "timestamp": time.time(),
        "request": user_id
    }

[Norcim133]

HTTP Request → Starlette → Middleware → FastMCP → JSON-RPC → Tool
     ↑                          ↓                               ↓
   (Any)                    (Can return                    (Must return
  Response)                 HTTP 401)                      JSON/data)

[Norcim133]

Whereupon, last question from me.

The above lets me access a global object from get_http_request but what if I want it back in with FastMCP Context?

Does starlette "state" automatically attach to Fastmcp "Context"?

I could do something like:

async def inject_user_context(ctx: Context) -> Context:
    """Dependency that injects user info into FastMCP context"""
    request = get_http_request()
    
    if hasattr(request, 'state'):
        ctx.user_id = getattr(request.state, 'user_id', None)
        ctx.ms_token = getattr(request.state, 'ms_token', None)
    
    return ctx

And add that as a dependency I think (or do it via a context wrapper).

But no point doubling up if context can somehow link to starlette already.