Rename TaskExecutionMode values to match updated spec

Update ToolExecution.taskSupport values per the latest MCP tasks spec:
- "never" → "forbidden"
- "always" → "required"
- "optional" unchanged

Add typed constants TASK_FORBIDDEN, TASK_OPTIONAL, TASK_REQUIRED for
consistent usage throughout the codebase instead of hardcoded strings.

Update all examples, tests, and documentation to use the new terminology.

Author: maxisbey

examples/clients/simple-task-interactive-client/README.md

@@ -49,7 +49,7 @@ async def sampling_callback(context, params) -> CreateMessageResult:
 ```python
 # Call a tool as a task (returns immediately with task reference)
 result = await session.experimental.call_tool_as_task("tool_name", {"arg": "value"})
-task_id = result.task.taskId
+task_id = result.taskSupport.taskId
 
 # Get result - this delivers elicitation/sampling requests and blocks until complete
 final = await session.experimental.get_task_result(task_id, CallToolResult)

examples/servers/simple-task-interactive/mcp_simple_task_interactive/server.py

@@ -69,13 +69,13 @@ async def list_tools() -> list[types.Tool]:
             name="confirm_delete",
             description="Asks for confirmation before deleting (demonstrates elicitation)",
             inputSchema={"type": "object", "properties": {"filename": {"type": "string"}}},
-            execution=types.ToolExecution(task="always"),
+            execution=types.ToolExecution(taskSupport=types.TASK_REQUIRED),
         ),
         types.Tool(
             name="write_haiku",
             description="Asks LLM to write a haiku (demonstrates sampling)",
             inputSchema={"type": "object", "properties": {"topic": {"type": "string"}}},
-            execution=types.ToolExecution(task="always"),
+            execution=types.ToolExecution(taskSupport=types.TASK_REQUIRED),
         ),
     ]
 
@@ -86,7 +86,7 @@ async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[types.T
     app = ctx.lifespan_context
 
     # Validate task mode
-    ctx.experimental.validate_task_mode("always")
+    ctx.experimental.validate_task_mode(types.TASK_REQUIRED)
 
     # Ensure handler is configured for response routing
     ensure_handler_configured(ctx.session, app)

examples/servers/simple-task/mcp_simple_task/server.py

@@ -41,7 +41,7 @@ async def list_tools() -> list[types.Tool]:
             name="long_running_task",
             description="A task that takes a few seconds to complete with status updates",
             inputSchema={"type": "object", "properties": {}},
-            execution=types.ToolExecution(task="always"),
+            execution=types.ToolExecution(taskSupport=types.TASK_REQUIRED),
         )
     ]
 
@@ -52,7 +52,7 @@ async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[types.T
     app = ctx.lifespan_context
 
     # Validate task mode - raises McpError(-32601) if client didn't use task augmentation
-    ctx.experimental.validate_task_mode("always")
+    ctx.experimental.validate_task_mode(types.TASK_REQUIRED)
 
     # Create the task
     metadata = ctx.experimental.task_metadata

src/mcp/shared/context.py

@@ -7,6 +7,8 @@
 from mcp.shared.session import BaseSession
 from mcp.types import (
     METHOD_NOT_FOUND,
+    TASK_FORBIDDEN,
+    TASK_REQUIRED,
     ClientCapabilities,
     ErrorData,
     RequestId,
@@ -54,12 +56,13 @@ def validate_task_mode(
         Validate that the request is compatible with the tool's task execution mode.
 
         Per MCP spec:
-        - "always": Clients MUST invoke as task. Server returns -32601 if not.
-        - "never" (or None): Clients MUST NOT invoke as task. Server returns -32601 if they do.
+        - "required": Clients MUST invoke as task. Server returns -32601 if not.
+        - "forbidden" (or None): Clients MUST NOT invoke as task. Server returns -32601 if they do.
         - "optional": Either is acceptable.
 
         Args:
-            tool_task_mode: The tool's execution.task value ("never", "optional", "always", or None)
+            tool_task_mode: The tool's execution.taskSupport value
+                ("forbidden", "optional", "required", or None)
             raise_error: If True, raises McpError on validation failure. If False, returns ErrorData.
 
         Returns:
@@ -69,16 +72,16 @@ def validate_task_mode(
             McpError: If invalid and raise_error=True
         """
 
-        mode = tool_task_mode or "never"
+        mode = tool_task_mode or TASK_FORBIDDEN
 
         error: ErrorData | None = None
 
-        if mode == "always" and not self.is_task:
+        if mode == TASK_REQUIRED and not self.is_task:
             error = ErrorData(
                 code=METHOD_NOT_FOUND,
                 message="This tool requires task-augmented invocation",
             )
-        elif mode == "never" and self.is_task:
+        elif mode == TASK_FORBIDDEN and self.is_task:
             error = ErrorData(
                 code=METHOD_NOT_FOUND,
                 message="This tool does not support task-augmented invocation",
@@ -107,24 +110,24 @@ def validate_for_tool(
         Returns:
             None if valid, ErrorData if invalid and raise_error=False
         """
-        mode = tool.execution.task if tool.execution else None
+        mode = tool.execution.taskSupport if tool.execution else None
         return self.validate_task_mode(mode, raise_error=raise_error)
 
     def can_use_tool(self, tool_task_mode: TaskExecutionMode | None) -> bool:
         """
         Check if this client can use a tool with the given task mode.
 
         Useful for filtering tool lists or providing warnings.
-        Returns False if tool requires "always" but client doesn't support tasks.
+        Returns False if tool requires "required" but client doesn't support tasks.
 
         Args:
-            tool_task_mode: The tool's execution.task value
+            tool_task_mode: The tool's execution.taskSupport value
 
         Returns:
             True if the client can use this tool, False otherwise
         """
-        mode = tool_task_mode or "never"
-        if mode == "always" and not self.client_supports_tasks:
+        mode = tool_task_mode or TASK_FORBIDDEN
+        if mode == TASK_REQUIRED and not self.client_supports_tasks:
             return False
         return True
 

src/mcp/types.py

@@ -1,6 +1,6 @@
 from collections.abc import Callable
 from datetime import datetime
-from typing import Annotated, Any, Generic, Literal, TypeAlias, TypeVar
+from typing import Annotated, Any, Final, Generic, Literal, TypeAlias, TypeVar
 
 from pydantic import BaseModel, ConfigDict, Field, FileUrl, RootModel
 from pydantic.networks import AnyUrl, UrlConstraints
@@ -39,7 +39,11 @@
 Role = Literal["user", "assistant"]
 RequestId = Annotated[int, Field(strict=True)] | str
 AnyFunction: TypeAlias = Callable[..., Any]
-TaskExecutionMode = Literal["never", "optional", "always"]
+
+TaskExecutionMode = Literal["forbidden", "optional", "required"]
+TASK_FORBIDDEN: Final[Literal["forbidden"]] = "forbidden"
+TASK_OPTIONAL: Final[Literal["optional"]] = "optional"
+TASK_REQUIRED: Final[Literal["required"]] = "required"
 
 
 class TaskMetadata(BaseModel):
@@ -1126,17 +1130,17 @@ class ToolExecution(BaseModel):
 
     model_config = ConfigDict(extra="allow")
 
-    task: TaskExecutionMode | None = None
+    taskSupport: TaskExecutionMode | None = None
     """
     Indicates whether this tool supports task-augmented execution.
     This allows clients to handle long-running operations through polling
     the task system.
 
-    - "never": Tool does not support task-augmented execution (default when absent)
+    - "forbidden": Tool does not support task-augmented execution (default when absent)
     - "optional": Tool may support task-augmented execution
-    - "always": Tool requires task-augmented execution
+    - "required": Tool requires task-augmented execution
 
-    Default: "never"
+    Default: "forbidden"
     """
 
 

tests/experimental/tasks/server/test_elicitation_flow.py

@@ -35,6 +35,7 @@
 )
 from mcp.shared.message import SessionMessage
 from mcp.types import (
+    TASK_REQUIRED,
     CallToolRequest,
     CallToolRequestParams,
     CallToolResult,
@@ -94,7 +95,7 @@ async def list_tools():
                     "type": "object",
                     "properties": {"data": {"type": "string"}},
                 },
-                execution=ToolExecution(task="always"),
+                execution=ToolExecution(taskSupport=TASK_REQUIRED),
             )
         ]
 

tests/experimental/tasks/server/test_integration.py

@@ -25,6 +25,7 @@
 from mcp.shared.message import SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.types import (
+    TASK_REQUIRED,
     CallToolRequest,
     CallToolRequestParams,
     CallToolResult,
@@ -83,7 +84,7 @@ async def list_tools():
                     "type": "object",
                     "properties": {"input": {"type": "string"}},
                 },
-                execution=ToolExecution(task="always"),
+                execution=ToolExecution(taskSupport=TASK_REQUIRED),
             )
         ]
 

tests/experimental/tasks/server/test_sampling_flow.py

@@ -35,6 +35,7 @@
 )
 from mcp.shared.message import SessionMessage
 from mcp.types import (
+    TASK_REQUIRED,
     CallToolRequest,
     CallToolRequestParams,
     CallToolResult,
@@ -95,7 +96,7 @@ async def list_tools():
                     "type": "object",
                     "properties": {"question": {"type": "string"}},
                 },
-                execution=ToolExecution(task="always"),
+                execution=ToolExecution(taskSupport=TASK_REQUIRED),
             )
         ]
 

tests/experimental/tasks/server/test_server.py

@@ -14,6 +14,9 @@
 from mcp.shared.message import SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.types import (
+    TASK_FORBIDDEN,
+    TASK_OPTIONAL,
+    TASK_REQUIRED,
     CallToolRequest,
     CallToolRequestParams,
     CallToolResult,
@@ -226,19 +229,19 @@ async def list_tools():
                 name="quick_tool",
                 description="Fast tool",
                 inputSchema={"type": "object", "properties": {}},
-                execution=ToolExecution(task="never"),
+                execution=ToolExecution(taskSupport=TASK_FORBIDDEN),
             ),
             Tool(
                 name="long_tool",
                 description="Long running tool",
                 inputSchema={"type": "object", "properties": {}},
-                execution=ToolExecution(task="always"),
+                execution=ToolExecution(taskSupport=TASK_REQUIRED),
             ),
             Tool(
                 name="flexible_tool",
                 description="Can be either",
                 inputSchema={"type": "object", "properties": {}},
-                execution=ToolExecution(task="optional"),
+                execution=ToolExecution(taskSupport=TASK_OPTIONAL),
             ),
         ]
 
@@ -251,11 +254,11 @@ async def list_tools():
     tools = result.root.tools
 
     assert tools[0].execution is not None
-    assert tools[0].execution.task == "never"
+    assert tools[0].execution.taskSupport == TASK_FORBIDDEN
     assert tools[1].execution is not None
-    assert tools[1].execution.task == "always"
+    assert tools[1].execution.taskSupport == TASK_REQUIRED
     assert tools[2].execution is not None
-    assert tools[2].execution.task == "optional"
+    assert tools[2].execution.taskSupport == TASK_OPTIONAL
 
 
 # --- Integration tests ---
@@ -274,7 +277,7 @@ async def list_tools():
                 name="long_task",
                 description="A long running task",
                 inputSchema={"type": "object", "properties": {}},
-                execution=ToolExecution(task="optional"),
+                execution=ToolExecution(taskSupport="optional"),
             )
         ]
 

tests/experimental/tasks/test_interactive_example.py

@@ -41,6 +41,7 @@
 )
 from mcp.shared.message import SessionMessage
 from mcp.types import (
+    TASK_REQUIRED,
     CallToolResult,
     CreateMessageRequestParams,
     CreateMessageResult,
@@ -79,13 +80,13 @@ async def list_tools() -> list[Tool]:
                 name="confirm_delete",
                 description="Asks for confirmation before deleting (demonstrates elicitation)",
                 inputSchema={"type": "object", "properties": {"filename": {"type": "string"}}},
-                execution=ToolExecution(task="always"),
+                execution=ToolExecution(taskSupport=TASK_REQUIRED),
             ),
             Tool(
                 name="write_haiku",
                 description="Asks LLM to write a haiku (demonstrates sampling)",
                 inputSchema={"type": "object", "properties": {"topic": {"type": "string"}}},
-                execution=ToolExecution(task="always"),
+                execution=ToolExecution(taskSupport=TASK_REQUIRED),
             ),
         ]
 
@@ -95,7 +96,7 @@ async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[TextCon
         app = ctx.lifespan_context
 
         # Validate task mode
-        ctx.experimental.validate_task_mode("always")
+        ctx.experimental.validate_task_mode(TASK_REQUIRED)
 
         # Ensure handler is configured for response routing
         session_id = id(ctx.session)