π The fast, Pythonic way to build MCP servers and clients.
tasks: run tools called from another tool in the foreground (#5275)
nate nowack57fb604cd27f
diff --git a/docs/servers/tasks.mdx b/docs/servers/tasks.mdxindex 77c1b4ae1..3bb9d579a 100644--- a/docs/servers/tasks.mdx+++ b/docs/servers/tasks.mdx@@ -111,6 +111,8 @@ The boolean shortcuts map to these modes:When a `mode="required"` tool is called by a client that didn't opt in, FastMCP returns a "missing required capability" error rather than running it synchronously.+A client's opt-in applies to the tool it called. When a tool, resource, or prompt calls a tool through `ctx.fastmcp.call_tool()`, as a [search transform's](/servers/transforms/tool-search) `call_tool` proxy and [CodeMode's](/servers/transforms/code-mode) `execute` do, the inner call runs in the foreground so the caller gets its result. An `"optional"` tool runs synchronously there, and a `"required"` tool raises a tool error, since only the client can start a task by calling it directly.+### Poll IntervalWhen a client polls for task status, the server can suggest how frequently to check back:diff --git a/fastmcp_slim/fastmcp/server/dependencies.py b/fastmcp_slim/fastmcp/server/dependencies.pyindex e8006c991..8c51c9fa2 100644--- a/fastmcp_slim/fastmcp/server/dependencies.py+++ b/fastmcp_slim/fastmcp/server/dependencies.py@@ -238,6 +238,61 @@ _background_task_session_id: ContextVar[str | None] = ContextVar()+class _ClientToolCall:+ """One ``tools/call`` a client sent, until its first dispatch claims it."""++ claimed: bool = False+++#: The wire ``tools/call`` being served. Per-request client settings, such as+#: the tasks opt-in, describe the tool the client named; the first dispatch of+#: that request claims them. Calls a tool body makes in turn, and reads of+#: resources or prompts, find nothing to claim.+_client_tool_call: ContextVar[_ClientToolCall | None] = ContextVar(+ "fastmcp_client_tool_call", default=None+)+++@contextmanager+def _serving_client_tool_call() -> Generator[None, None, None]:+ token = _client_tool_call.set(_ClientToolCall())+ try:+ yield+ finally:+ _client_tool_call.reset(token)+++def _claim_client_tool_call() -> bool:+ """True once per client ``tools/call``: for the dispatch the client addressed."""+ call = _client_tool_call.get()+ if call is None or call.claimed:+ return False+ call.claimed = True+ return True+++#: Whether the ``call_tool`` dispatch in progress is the client's own call. Each+#: dispatch sets it on entry, before middleware runs, so a tool that middleware+#: or a tool body calls sets its own (False) value without disturbing this one.+_client_dispatch: ContextVar[bool] = ContextVar(+ "fastmcp_client_dispatch", default=False+)+++@contextmanager+def _dispatching_tool_call() -> Generator[None, None, None]:+ token = _client_dispatch.set(_claim_client_tool_call())+ try:+ yield+ finally:+ _client_dispatch.reset(token)+++def _is_client_tool_call() -> bool:+ """Whether the tool being dispatched is the one the client's ``tools/call`` named."""+ return _client_dispatch.get()++# --- Docket availability check ---_DOCKET_AVAILABLE: bool | None = Nonediff --git a/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.pyindex 5e96e37dc..265b8a771 100644--- a/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py+++ b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py@@ -31,7 +31,11 @@ from fastmcp.exceptions import (from fastmcp.prompts.base import InputRequiredPromptResultfrom fastmcp.resources.base import InputRequiredResourceResultfrom fastmcp.server.completions import CompletionValues, normalize_completion-from fastmcp.server.dependencies import bind_request_context, extract_version_spec+from fastmcp.server.dependencies import (+ _serving_client_tool_call,+ bind_request_context,+ extract_version_spec,+)from fastmcp.tools.base import InputRequiredToolResult, ToolResultfrom fastmcp.utilities.async_utils import (call_sync_fn_in_threadpool,@@ -243,7 +247,8 @@ class MCPOperationsMixin:version = _version_from_ctx(ctx)try:- result = await self.call_tool(key, arguments, version=version)+ with _serving_client_tool_call():+ result = await self.call_tool(key, arguments, version=version)except (DisabledError, NotFoundError):# Unknown/disabled tool: return an error result (matching the# v1 SDK's call_tool behavior) so the client surfaces adiff --git a/fastmcp_slim/fastmcp/server/server.py b/fastmcp_slim/fastmcp/server/server.pyindex 001b3ce3e..8987b94bd 100644--- a/fastmcp_slim/fastmcp/server/server.py+++ b/fastmcp_slim/fastmcp/server/server.py@@ -76,6 +76,7 @@ from fastmcp.resources.template import ResourceTemplatefrom fastmcp.server.auth import AuthCheck, AuthContext, AuthProvider, run_auth_checksfrom fastmcp.server.caching import build_cache_hintsfrom fastmcp.server.completions import CompletionHandler+from fastmcp.server.dependencies import _dispatching_tool_callfrom fastmcp.server.lifespan import Lifespanfrom fastmcp.server.low_level import LowLevelServerfrom fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext@@ -1446,17 +1447,18 @@ class FastMCP(# the whole thing (so it observes every call), and the# interceptors sit between it and the tool body (so each is the# last gate before execution).- dispatched = await self._dispatch_component_middleware(- context=mw_context,- call_next=self._compose_tool_call_interceptors(- lambda context: self.call_tool(- context.message.name,- context.message.arguments or {},- version=version,- run_middleware=False,- )- ),- )+ with _dispatching_tool_call():+ dispatched = await self._dispatch_component_middleware(+ context=mw_context,+ call_next=self._compose_tool_call_interceptors(+ lambda context: self.call_tool(+ context.message.name,+ context.message.arguments or {},+ version=version,+ run_middleware=False,+ )+ ),+ )# Above the chain, so a Prefab payload is re-addressed however# it was produced β middleware can answer a call itself, and# such a result never reaches the core path below.diff --git a/fastmcp_tasks/fastmcp_tasks/extension.py b/fastmcp_tasks/fastmcp_tasks/extension.pyindex 7ba4f123d..331125a7b 100644--- a/fastmcp_tasks/fastmcp_tasks/extension.py+++ b/fastmcp_tasks/fastmcp_tasks/extension.py@@ -36,8 +36,12 @@ from mcp.shared.inbound import MCP_NAME_HEADER, decode_header_valuefrom mcp_types.jsonrpc import HEADER_MISMATCHfrom mcp_types.version import MODERN_PROTOCOL_VERSIONS-from fastmcp.exceptions import NotFoundError-from fastmcp.server.dependencies import extract_version_spec, get_http_request+from fastmcp.exceptions import NotFoundError, ToolError+from fastmcp.server.dependencies import (+ _is_client_tool_call,+ extract_version_spec,+ get_http_request,+)from fastmcp.server.extensions import (MethodBinding,ServerExtension,@@ -223,6 +227,11 @@ class TasksExtension(ServerExtension):opt in), ``optional`` tasks only when the client opted in, ``forbidden``never tasks. A non-task call passes straight through to the tool body."""+ # The client's opt-in covers the tool it named. A tool that middleware,+ # a tool body (a search proxy, CodeMode's execute), a resource, or a+ # prompt calls in turn runs in the foreground and returns inline.+ from_client = _is_client_tool_call()+# Resolve the same version core would dispatch: a versioned tools/call# carries its VersionSpec in the request _meta, so omitting it here would# task the highest version even when the client targeted an older one@@ -252,6 +261,14 @@ class TasksExtension(ServerExtension):)mode = tool.task_config.mode+ if not from_client:+ if mode == "required":+ raise ToolError(+ f"Tool {tool.name!r} only runs as a background task, which "+ "the client has to request by calling it directly."+ )+ return await call_next()+if mode == "required":if not opted_in:raise MCPError(diff --git a/tests/tasks/server/test_extension.py b/tests/tasks/server/test_extension.pyindex 44dc7ef9c..669ccee46 100644--- a/tests/tasks/server/test_extension.py+++ b/tests/tasks/server/test_extension.py@@ -28,7 +28,7 @@ from mcp.shared.exceptions import MCPErrorfrom fastmcp import Context, FastMCPfrom fastmcp.client import Clientfrom fastmcp.exceptions import ToolError-from fastmcp.server.dependencies import bind_request_context+from fastmcp.server.dependencies import _serving_client_tool_call, bind_request_contextfrom fastmcp.tools.base import ToolResultfrom fastmcp.utilities.tasks import TASKS_EXTENSION_ID, TaskConfigfrom fastmcp_tasks import TasksExtension@@ -374,7 +374,7 @@ async def test_legacy_era_required_tool_raises_missing_capability():"_meta": opt_in_meta(),},)- with bind_request_context(srctx):+ with bind_request_context(srctx), _serving_client_tool_call():with pytest.raises(MCPError) as exc_info:await mcp.call_tool("must_task", {"n": 3})assert exc_info.value.error.code == -32021diff --git a/tests/tasks/server/test_task_catalog_transforms.py b/tests/tasks/server/test_task_catalog_transforms.pyindex b3d5bcce3..3cf41f199 100644--- a/tests/tasks/server/test_task_catalog_transforms.py+++ b/tests/tasks/server/test_task_catalog_transforms.py@@ -10,9 +10,12 @@ from __future__ import annotationsfrom collections.abc import Sequenceimport pytest+from fastmcp_tasks.client import call_tool_task-from fastmcp import Client, FastMCP+from fastmcp import Client, Context, FastMCP+from fastmcp.exceptions import ToolErrorfrom fastmcp.experimental.transforms.code_mode import CodeMode+from fastmcp.server.middleware import Middlewarefrom fastmcp.server.transforms import Namespacefrom fastmcp.server.transforms.catalog import CatalogTransformfrom fastmcp.server.transforms.search import BM25SearchTransform, RegexSearchTransform@@ -110,3 +113,115 @@ async def test_task_tool_added_by_catalog_transform_is_registered():"slow_thing","synthetic_slow",]+++class TestNestedCallsRunInForeground:+ """A client's tasks opt-in covers the tool it called, not tools that tool calls."""++ async def test_search_proxy_returns_task_tool_result(self):+ mcp = make_server()+ mcp.add_transform(BM25SearchTransform())++ async with Client(mcp) as client:+ result = await client.call_tool(+ "call_tool", {"name": "slow_thing", "arguments": {"n": 2}}+ )++ assert result.structured_content == {"n": 2}++ async def test_code_mode_returns_task_tool_result(self):+ mcp = make_server()+ mcp.add_transform(CodeMode())++ async with Client(mcp) as client:+ result = await client.call_tool(+ "execute",+ {"code": "return await call_tool('slow_thing', {'n': 4})"},+ )++ assert "4" in result.content[0].text++ async def test_tool_calling_task_tool_gets_its_result(self):+ mcp = make_server()++ @mcp.tool+ async def outer(ctx: Context) -> dict:+ result = await ctx.fastmcp.call_tool("slow_thing", {"n": 5})+ return result.structured_content or {}++ async with Client(mcp) as client:+ result = await client.call_tool("outer", {})++ assert result.structured_content == {"n": 5}++ async def test_required_task_tool_refuses_nested_call(self):+ mcp = make_server()++ @mcp.tool(task=TaskConfig(mode="required"))+ async def must_task(n: int) -> dict:+ return {"n": n}++ mcp.add_transform(BM25SearchTransform())++ async with Client(mcp) as client:+ with pytest.raises(ToolError, match="only runs as a background task"):+ await client.call_tool(+ "call_tool", {"name": "must_task", "arguments": {"n": 1}}+ )++ async def test_resource_and_prompt_get_task_tool_result(self):+ mcp = make_server()++ @mcp.resource("data://thing")+ async def thing(ctx: Context) -> dict:+ result = await ctx.fastmcp.call_tool("slow_thing", {"n": 6})+ return result.structured_content or {}++ @mcp.prompt+ async def ask(ctx: Context) -> str:+ result = await ctx.fastmcp.call_tool("slow_thing", {"n": 7})+ return str(result.structured_content)++ async with Client(mcp) as client:+ resource = await client.read_resource("data://thing")+ prompt = await client.get_prompt("ask")++ assert "6" in resource[0].text+ assert "7" in prompt.messages[0].content.text++ async def test_in_process_client_inside_tool_can_still_task(self):+ other = make_server()+ front = FastMCP("front")++ @front.tool+ async def relay() -> str:+ async with Client(other) as inner:+ task = await call_tool_task(inner, "slow_thing", {"n": 8})+ return task.task_id++ async with Client(front) as client:+ result = await client.call_tool("relay", {})++ assert result.data++ async def test_middleware_calling_a_tool_keeps_the_client_opt_in(self):+ mcp = make_server()++ @mcp.tool+ async def policy() -> str:+ return "ok"++ class CheckPolicyFirst(Middleware):+ async def on_call_tool(self, context, call_next):+ if context.message.name != "policy":+ assert context.fastmcp_context is not None+ await context.fastmcp_context.fastmcp.call_tool("policy", {})+ return await call_next(context)++ mcp.add_middleware(CheckPolicyFirst())++ async with Client(mcp) as client:+ task = await call_tool_task(client, "slow_thing", {"n": 9})+ result = await task.result()++ assert result.structured_content == {"n": 9}diff --git a/tests/tasks/task_helpers.py b/tests/tasks/task_helpers.pyindex 405996ada..7424336fb 100644--- a/tests/tasks/task_helpers.py+++ b/tests/tasks/task_helpers.py@@ -41,7 +41,7 @@ from mcp.server.session import ServerSessionfrom mcp_types import CLIENT_CAPABILITIES_META_KEYfrom fastmcp.server.auth import AccessToken-from fastmcp.server.dependencies import bind_request_context+from fastmcp.server.dependencies import _serving_client_tool_call, bind_request_contextfrom fastmcp.server.server import FastMCPfrom fastmcp.utilities.tasks import TASKS_EXTENSION_ID@@ -98,7 +98,7 @@ def _opted_in_request(method="tools/call",params=params,)- with bind_request_context(srctx):+ with bind_request_context(srctx), _serving_client_tool_call():yield@@ -133,7 +133,7 @@ async def call_tool_without_optin(access_token: AccessToken | None = None,):"""Run a `tools/call` with no tasks opt-in (synchronous unless mode=required)."""- with auth_scope(access_token):+ with auth_scope(access_token), _serving_client_tool_call():return await server.call_tool(name, arguments or {})