Fix MCP server error -32602: Authorization header lost in background tasks

[Copilot]

FastMCP's streamable_http stateless transport processes JSON-RPC messages (e.g. initialize) in background asyncio tasks where Starlette's request context is unavailable. UserAuthMiddleware crashed trying to read Authorization from the torn-down request context, surfacing as MCP error -32602.

Changes

ex_app/lib/mcp_server.py

• Add _mcp_auth_header: ContextVar[str | None] — asyncio copies the context snapshot when spawning tasks, so a value set here before task creation survives inside the task after the request context is gone
• Add MCPAuthHeaderMiddleware (pure-ASGI) — captures Authorization from every HTTP request into _mcp_auth_header before FastMCP takes ownership
• Update UserAuthMiddleware.on_message() — reads from _mcp_auth_header first; falls back to live Starlette request context for forward-compatibility
• Guard ToolListMiddleware.on_message() with nc is not None — prevents a secondary crash on pre-auth messages like initialize where nc hasn't been set yet

ex_app/lib/main.py

• Import MCPAuthHeaderMiddleware and register it on APP immediately after AppAPIAuthMiddleware

APP.add_middleware(AppAPIAuthMiddleware)     # validates Nextcloud app-API signature
APP.add_middleware(MCPAuthHeaderMiddleware)  # snapshots Authorization into ContextVar before FastMCP tasks are spawned

The ContextVar propagation relies on the fact that asyncio.create_task() takes a copy of the current context at task-creation time, so _mcp_auth_header is readable inside any background task spawned during request handling — even after Starlette tears down its own request context object.

Original prompt

Fix: MCP server fails with "Context is not available outside of a request" (-32602)

Problem

When connecting to the MCP server via MCP Inspector or other MCP clients, requests fail with MCP error -32602: Invalid request parameters. The docker logs show:

WARNING - Failed to validate request: Context is not available outside of a request

There are two root causes:

1. Wrong Authorization header format in docs: The docs say to use Authorization: Bearer <app-password>, but the Nextcloud App API proxy intercepts Bearer tokens and returns an HTML login page. The correct format is Authorization: Basic base64(username:app-password).

2. FastMCP background task context loss: The streamable_http transport in stateless mode processes MCP JSON-RPC messages (like initialize) in a background task, outside the original FastAPI request lifecycle. UserAuthMiddleware tries to read the Authorization header from context.fastmcp_context.request_context.request.headers, but Starlette's request context is not propagated into background tasks, causing the crash.

Fix

ex_app/lib/mcp_server.py — replace the entire file with:

# SPDX-FileCopyrightText: 2024 LangChain, Inc.
# SPDX-License-Identifier: MIT
import time
import asyncio
import inspect
import logging
from contextvars import ContextVar
from functools import wraps

from fastmcp.server.dependencies import get_context
from nc_py_api import AsyncNextcloudApp, NextcloudApp
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext
from fastmcp.tools import Tool
from mcp import types as mt
from ex_app.lib.tools import get_tools
import requests

logger = logging.getLogger(__name__)

# ContextVar to propagate the Authorization header into FastMCP background tasks.
# asyncio.create_task() copies the current context snapshot at task-creation time,
# so a ContextVar set before the task is spawned is visible inside it — even after
# Starlette's request context has been torn down.
_mcp_auth_header: ContextVar[str | None] = ContextVar("_mcp_auth_header", default=None)


class MCPAuthHeaderMiddleware:
    """Pure-ASGI middleware that captures the Authorization header from every
    HTTP request and stores it in a ContextVar.

    Must be added to the outer FastAPI app (APP) so it runs before FastMCP takes
    ownership of the request. Because asyncio copies the current context when
    spawning tasks, the ContextVar value is available inside FastMCP's background-
    task processing even after the original Starlette request context is gone.
    """

    def __init__(self, app):
        self.app = app

    async def __call__(self, scope, receive, send):
        if scope["type"] == "http":
            headers = {k: v for k, v in scope.get("headers", [])}
            raw_auth = headers.get(b"authorization", b"")
            auth_value = raw_auth.decode("latin-1") if raw_auth else None
            token = _mcp_auth_header.set(auth_value)
            try:
                await self.app(scope, receive, send)
            finally:
                _mcp_auth_header.reset(token)
        else:
            await self.app(scope, receive, send)


def get_user(authorization_header: str, nc: AsyncNextcloudApp) -> str:
    response = requests.get(
        f"{nc.app_cfg.endpoint}/ocs/v2.php/cloud/user",
        headers={
            "Accept": "application/json",
            "Ocs-Apirequest": "1",
            "Authorization": authorization_header,
        },
    )
    if response.status_code != 200:
        raise Exception("Failed to get user info")
    return response.json()["ocs"]["data"]["id"]


class UserAuthMiddleware(Middleware):
    async def on_message(self, context: MiddlewareContext, call_next):
        # 1. Primary path: read from ContextVar — always works, including inside
        #    FastMCP background tasks where the Starlette request context is gone.
        authorization_header = _mcp_auth_header.get()

        # 2. Fallback: try the live request context (works for non-background paths
        #    and keeps compatibility if the transport behaviour changes).
        if authorization_header is None:
            try:
                authorization_header = (
                    context.fastmcp_context.request_context.request.headers.get("Authorization")
                )
            except Exception:
                pass

        if not authorization_header:
            raise Exception("Authorization header is missing/invalid")

        nc = AsyncNextcloudApp()
        user = get_user(authorization_header, nc)
        await nc.set_user(user)
        context.fastmcp_context.set_state("nextcloud", nc)
        return await call_next(context)


LAST_MCP_TOOL_UPDATE = 0


class ToolListMiddleware(Middleware):
    def __init__(self, mcp):
        self.mcp = mcp

    async def on_message(
            self,
            context: MiddlewareContext[mt.ListToolsRequest],
            call_next: CallNext[mt.ListToolsRequest,...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[Copilot]

Pull request overview

This PR addresses MCP JSON-RPC failures (-32602) caused by FastMCP processing stateless streamable_http messages in background asyncio tasks where Starlette’s request context is no longer available, which previously broke UserAuthMiddleware when reading the Authorization header.

Changes:

• Introduces an ASGI middleware (MCPAuthHeaderMiddleware) plus a ContextVar to snapshot and propagate the Authorization header into FastMCP background tasks.
• Updates UserAuthMiddleware to prefer the ContextVar value and fall back to the live request context when available.
• Prevents ToolListMiddleware from crashing on unauthenticated / pre-auth message flows by guarding tool refresh on nextcloud state being present.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
ex_app/lib/mcp_server.py	Adds ContextVar-backed auth header propagation middleware; updates auth and tool-list middleware to avoid request-context and pre-auth crashes.
ex_app/lib/main.py	Registers MCPAuthHeaderMiddleware on the outer FastAPI app so the header snapshot is available before FastMCP background tasks run.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janepie]

@R0Wi are you planning to get this PR into a more refined state at some point? It would be nice, but right now it is a bit too raw for us to review this. Please have a look at our newly released AI policy for all contributions within Nextcloud: https://github.com/nextcloud/.github/blob/master/AI_POLICY.md

[janepie]

Superseded by #174