Skip to content

Server-wide tasks=True default is ignored by add_tool() and the tools= constructor parameter #5782

Open

Description

@BlueX888

Server-wide tasks=True default is ignored by add_tool() and the tools= constructor parameter

What happened?

On a server created with FastMCP(..., tasks=True), background task support is only applied to tools registered through the @mcp.tool decorator. The same function registered any other way silently ends up with task_config.mode == "forbidden":

  • mcp.add_tool(fn) for a plain function
  • FastMCP(..., tools=[fn])
  • mcp.add_tool(fn) where fn uses the standalone @tool decorator without an explicit task=

The docs for the Server-Wide Default say tasks=True enables "background task support for all tools by default" (https://gofastmcp.com/servers/tasks). A tool that is task-forbidden is invisible to the tasks extension: an opted-in client gets a foreground result instead of a CreateTaskResult, and the tool is never registered with Docket.

The inconsistency also cuts through the sync-function guard: on a tasks=True server, @mcp.tool on a sync function raises ValueError (matching the documented Warning about synchronous tools), but mcp.add_tool(sync_fn) registers it silently.

Example Code

import asyncio

from fastmcp import FastMCP


async def my_tool() -> str:
    return "ok"


async def main():
    # Path 1: add_tool()
    mcp = FastMCP("test", tasks=True)
    mcp.add_tool(my_tool)
    tool = await mcp.get_tool("my_tool")
    print("add_tool:", tool.task_config.mode)

    # Path 2: tools= constructor parameter
    mcp2 = FastMCP("test", tasks=True, tools=[my_tool])
    tool2 = await mcp2.get_tool("my_tool")
    print("tools=:", tool2.task_config.mode)

    # Contrast: the identical function via the decorator
    mcp3 = FastMCP("test", tasks=True)

    @mcp3.tool
    async def my_tool2() -> str:
        return "ok"

    tool3 = await mcp3.get_tool("my_tool2")
    print("@mcp.tool:", tool3.task_config.mode)


asyncio.run(main())

Output on current main (fails at fb52bd36):

add_tool: forbidden
tools=: forbidden
@mcp.tool: optional

Expected: optional on all three paths. Additionally, mcp.add_tool(sync_fn) on a tasks=True server should raise the same ValueError that @mcp.tool raises for sync functions ("... uses a sync function but has task execution enabled. Background tasks require async functions."), instead of registering silently.

Root cause

The server default (FastMCP._support_tasks_by_default) is merged in only one place: the @mcp.tool path in fastmcp/server/server.py (task=task if task is not None else self._support_tasks_by_default). FastMCP.add_tool() delegates straight to LocalProvider.add_tool(), which resolves an unset task setting to False in the @tool-metadata branch and passes no task at all in the plain-function branch (fastmcp/server/providers/local_provider/decorators/tools.py), and the tools= constructor loop converts callables via Tool.from_function(tool) before add_tool() ever sees them — so the default never applies on those paths.

Verified on main at fb52bd36; I have a minimal fix ready that makes all registration paths inherit the default (and reuses the existing sync-function guard) and can open a PR.

Version Information

FastMCP version: 4.1.1.dev5+fb52bd36
MCP version: 2.0.0
Python version: 3.12.2
Platform: Windows-11-10.0.26200-SP0

Activity

  1. added
    bugSomething isn't working. Reports of errors, unexpected behavior, or broken functionality.
    serverRelated to FastMCP server implementation or server-side functionality.
    on Oct 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working. Reports of errors, unexpected behavior, or broken functionality.serverRelated to FastMCP server implementation or server-side functionality.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions