Skip to content

πŸš€ 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.mdx
index 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 Interval
When 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.py
index 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 = None
diff --git a/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py b/fastmcp_slim/fastmcp/server/mixins/mcp_operations.py
index 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 InputRequiredPromptResult
from fastmcp.resources.base import InputRequiredResourceResult
from 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, ToolResult
from 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 a
diff --git a/fastmcp_slim/fastmcp/server/server.py b/fastmcp_slim/fastmcp/server/server.py
index 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 ResourceTemplate
from fastmcp.server.auth import AuthCheck, AuthContext, AuthProvider, run_auth_checks
from fastmcp.server.caching import build_cache_hints
from fastmcp.server.completions import CompletionHandler
+from fastmcp.server.dependencies import _dispatching_tool_call
from fastmcp.server.lifespan import Lifespan
from fastmcp.server.low_level import LowLevelServer
from 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.py
index 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_value
from mcp_types.jsonrpc import HEADER_MISMATCH
from 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.py
index 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 MCPError
from fastmcp import Context, FastMCP
from fastmcp.client import Client
from fastmcp.exceptions import ToolError
-from fastmcp.server.dependencies import bind_request_context
+from fastmcp.server.dependencies import _serving_client_tool_call, bind_request_context
from fastmcp.tools.base import ToolResult
from fastmcp.utilities.tasks import TASKS_EXTENSION_ID, TaskConfig
from 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 == -32021
diff --git a/tests/tasks/server/test_task_catalog_transforms.py b/tests/tasks/server/test_task_catalog_transforms.py
index 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 annotations
from collections.abc import Sequence
import pytest
+from fastmcp_tasks.client import call_tool_task
-from fastmcp import Client, FastMCP
+from fastmcp import Client, Context, FastMCP
+from fastmcp.exceptions import ToolError
from fastmcp.experimental.transforms.code_mode import CodeMode
+from fastmcp.server.middleware import Middleware
from fastmcp.server.transforms import Namespace
from fastmcp.server.transforms.catalog import CatalogTransform
from 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.py
index 405996ada..7424336fb 100644
--- a/tests/tasks/task_helpers.py
+++ b/tests/tasks/task_helpers.py
@@ -41,7 +41,7 @@ from mcp.server.session import ServerSession
from mcp_types import CLIENT_CAPABILITIES_META_KEY
from fastmcp.server.auth import AccessToken
-from fastmcp.server.dependencies import bind_request_context
+from fastmcp.server.dependencies import _serving_client_tool_call, bind_request_context
from fastmcp.server.server import FastMCP
from 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 {})