SEP-1686: Tasks by maxisbey · Pull Request #1645 · modelcontextprotocol/python-sdk

maxisbey · 2025-11-19T22:34:54Z

SEP-1686: Tasks Implementation

This PR implements the experimental Tasks feature from the MCP specification, enabling asynchronous request handling with polling-based result retrieval.

Summary

Tasks allow servers to handle long-running operations asynchronously. Instead of blocking until completion, the server creates a task, returns immediately, and the client polls for status and retrieves results when ready.

Key Features

Server-side:

server.experimental.enable_tasks() - One-line setup that registers all task handlers
ctx.experimental.run_task(work) - Simplified pattern for spawning background work
ServerTaskContext with elicit(), elicit_url(), create_message() for user interaction
Automatic task lifecycle management (auto-complete on return, auto-fail on exception)
Custom TaskStore interface for production deployments

Client-side:

session.experimental.call_tool_as_task() - Call tools with task augmentation
session.experimental.poll_task() - Async iterator for polling until terminal state
session.experimental.get_task_result() - Retrieve final results
ExperimentalTaskHandlers - Handle task-augmented requests from servers

Bidirectional Flow:

Client → Server: Task-augmented tool calls
Server → Client: Task-augmented elicitation and sampling
Full support for nested task scenarios

Implementation Details

Core Components

Component	Purpose
`TaskStore`	Abstract interface for task state persistence
`InMemoryTaskStore`	Development/testing implementation
`TaskMessageQueue`	Queue for delivering requests via `tasks/result`
`TaskResultHandler`	Handles `tasks/result` with dequeue-send-wait pattern
`ServerTaskContext`	Task execution context with elicit/sampling support
`ExperimentalServerSessionFeatures`	Server→client task operations
`ExperimentalClientFeatures`	Client→server task operations

Task Lifecycle

working → completed | failed | cancelled
working → input_required → working → ...

Validation

Shared validation module (mcp/server/validation.py) for sampling tools and message structure
Capability checking isolated in mcp/shared/experimental/tasks/capabilities.py
Proper error codes and messages per spec

Testing

220+ tests covering all task functionality
100% code coverage on tasks-related code
Integration tests for all four elicitation scenarios:
1. Normal tool call + normal elicitation
2. Normal tool call + task-augmented elicitation
3. Task-augmented tool call + normal elicitation
4. Task-augmented tool call + task-augmented elicitation
Deterministic tests using events instead of sleeps

Documentation

Comprehensive documentation rewritten from scratch:

docs/experimental/tasks.md - Overview, lifecycle, concepts
docs/experimental/tasks-server.md - Server implementation guide
docs/experimental/tasks-client.md - Client usage guide

Examples

Two example servers demonstrating tasks:

examples/servers/simple-task/ - Basic task with status updates
examples/servers/simple-task-interactive/ - Tasks with elicitation and sampling

Breaking Changes

None - all task functionality is under the experimental namespace.

Types of changes

New feature (non-breaking change which adds functionality)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Analyzed the official SEP-1686 specification against both the MCP SDK's draft implementation (PR #1645) and FastMCP's current shims. Made corrections to match the spec exactly. **Key changes:** 1. **Removed `error` field** - Spec only defines `statusMessage` for error details. Changed all handlers to use `statusMessage` instead of separate `error` field. 2. **Removed non-spec status values** - Spec defines exactly 5 statuses: `working`, `input_required`, `completed`, `failed`, `cancelled`. Removed FastMCP's `"submitted"` and `"unknown"` extensions. 3. **Non-existent tasks raise errors** - Aligned with SDK behavior: `tasks/get` for non-existent/deleted tasks raises `ValueError` (JSON-RPC error) instead of returning synthetic `status="unknown"`. 4. **Test updates** - Fixed 12+ tests expecting removed statuses. Changed assertions to expect JSON-RPC errors for not-found scenarios. **What stayed the same:** - Client already sends both `task=` (spec-compliant) and `_meta=` (SDK compatibility) - Server monkeypatches work correctly for request params - `createdAt` as ISO 8601 string matches spec (SDK uses datetime but serializes same) - `ttl` field naming confirmed correct in both spec and SDK All 3270 tests passing. FastMCP is now fully aligned with SEP-1686 final specification. Related: modelcontextprotocol/python-sdk#1645 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

src/mcp/types.py

src/mcp/server/lowlevel/server.py

- Move task handler protocols to experimental/task_handlers.py - Add build_client_tasks_capability() helper to auto-build ClientTasksCapability from handlers - ClientSession now automatically infers tasks capability from provided handlers - Add Resolver class for async result handling in task message queues - Refactor result_handler to use Resolver pattern - Add test for auto-built capabilities from handlers

- Replace 6 individual task handler parameters with single `experimental_task_handlers: ExperimentalTaskHandlers` (keyword-only) - ExperimentalTaskHandlers dataclass groups all handlers and provides: - `build_capability()` - auto-builds ClientTasksCapability from handlers - `handles_request()` - checks if request is task-related - `handle_request()` - dispatches to appropriate handler - Simplify ClientSession._received_request by delegating task requests - Update tests to use new ExperimentalTaskHandlers API

This commit adds working examples for the Tasks SEP demonstrating elicitation and sampling flows, along with supporting infrastructure changes. Examples: - simple-task-interactive server: Exposes confirm_delete (elicitation) and write_haiku (sampling) tools that run as tasks - simple-task-interactive-client: Connects to server, handles callbacks, and demonstrates the correct task result retrieval pattern Key changes: - Move call_tool_as_task() from ClientSession to session.experimental.call_tool_as_task() for API consistency - Add comprehensive tests mirroring the example patterns - Add server-side print outputs for visibility into task execution The critical insight: clients must call get_task_result() to receive elicitation/sampling requests - simply polling get_task() will not trigger the callbacks.

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.

This addresses two critical spec compliance gaps: 1. Add `lastUpdatedAt` field to Task model - Required by spec: ISO 8601 timestamp updated on every status change - Added to Task model in types.py - Initialized alongside createdAt in create_task_state() - Updated in InMemoryTaskStore.update_task() on any change - Included in all Task responses and notifications 2. Add related-task metadata to tasks/result response - Per spec: tasks/result MUST include _meta with io.modelcontextprotocol/related-task containing the taskId - Required because result structure doesn't contain task ID - Merges with any existing _meta from stored result

The MCP Tasks spec requires clients to poll tasks/get watching for status changes, then call tasks/result when status becomes input_required to receive elicitation/sampling requests. - Add poll_task() async iterator to ExperimentalClientFeatures that yields status on each poll and respects the server's pollInterval hint - Update simple-task-client to use poll_task() instead of manual loop - Update simple-task-interactive-client to poll first, then call tasks/result on input_required per the spec pattern

This implements the bidirectional task-augmented request pattern where the server can send task-augmented elicitation/sampling requests to the client, and the client can defer processing by returning CreateTaskResult. Key changes: - Add ExperimentalServerSessionFeatures with get_task(), get_task_result(), poll_task(), elicit_as_task(), and create_message_as_task() methods for server→client task operations - Add shared polling utility (poll_until_terminal) used by both client and server to avoid code duplication - Add elicit_as_task() and create_message_as_task() to ServerTaskContext for use inside task-augmented tool calls - Add capability checks for task-augmented elicitation/sampling in ServerSession.check_client_capability() - Add comprehensive tests for all four elicitation scenarios: 1. Normal tool call + normal elicitation 2. Normal tool call + task-augmented elicitation 3. Task-augmented tool call + normal elicitation 4. Task-augmented tool call + task-augmented elicitation The implementation correctly handles the complex bidirectional flow where the server polls the client while the client's tasks/result call is still blocking, waiting for the tool task to complete.

Move all task-related capability checking logic into mcp/shared/experimental/tasks/capabilities.py to keep tasks code isolated from core session code. Changes: - Create capabilities.py with check_tasks_capability() and require_* helpers - Update ServerSession to import and use the shared function - Update ServerTaskContext to use require_* helpers instead of inline checks - Add missing capability checks to ExperimentalServerSessionFeatures This improves code organization and fixes a bug where session.experimental.elicit_as_task() wasn't checking capabilities.

- Add test_capabilities.py with unit tests for all capability checking functions - Add tests for elicit_as_task and create_message_as_task without handler - Add scenario 4 sampling test (task-augmented tool call + task-augmented sampling) - Replace sleep-based polling with event-based synchronization for faster, deterministic tests - Simplify for/else patterns in test code - Add additional check_tasks_capability edge case tests Test coverage improved to 99.94% with 0 missing statements.

This refactoring ensures all sampling and elicitation code paths use consistent validation and support the same features. Sampling changes: - Add shared validation module (mcp/server/validation.py) with validate_sampling_tools() and validate_tool_use_result_messages() - Add tools and tool_choice parameters to all sampling methods: - _build_create_message_request() - ExperimentalServerSessionFeatures.create_message_as_task() - ServerTaskContext.create_message() - ServerTaskContext.create_message_as_task() - Refactor ServerSession.create_message() to use shared validation Elicitation changes: - Rename _build_elicit_request to _build_elicit_form_request for clarity - Add _build_elicit_url_request() for URL mode elicitation - Add ServerTaskContext.elicit_url() so URL elicitation can be used from inside task-augmented tool calls (e.g., for OAuth flows) This fixes a gap where task-augmented code paths were missing: - tools/tool_choice parameters for sampling - URL mode for elicitation

- Add tests for validation.py (check_sampling_tools_capability, validate_sampling_tools, validate_tool_use_result_messages) - Add flow test for elicit_url() in ServerTaskContext - Add pragma no cover comments to defensive _meta checks in builder methods (model_dump never includes _meta with current types) - Fix test code to use assertions instead of conditional branches - Add pragma no branch to polling loops in test scenarios

Extract tool-specific logic into separate handler functions, keeping the call_tool decorator handler simple - it just dispatches based on tool name and returns an error for unknown tools.

- Remove section header comments from test files - Move all inline imports to top of files - Replace hardcoded error codes (-32600) with INVALID_REQUEST constant - Replace arbitrary sleeps with polling loops for deterministic tests - Add pragma no branch to polling conditions that always succeed on first try

…vents - Remove redundant '# Should not raise' comments in test_capabilities.py - Remove redundant '# No handler' comments in test_server_task_context.py - Replace arbitrary sleeps with deterministic event-based synchronization in test_task_result_handler.py (poll for wait events before proceeding)

Completely rewrote the experimental tasks documentation to cover the new simplified API and advanced features: tasks.md (Overview): - Clear task lifecycle diagram - Bidirectional flow explanation (client↔server) - Key concepts (metadata, store, capabilities) - Quick example with new enable_tasks() + run_task() API tasks-server.md (Server Guide): - Quick start with enable_tasks() + run_task() - Tool declaration (TASK_REQUIRED/OPTIONAL/FORBIDDEN) - Status updates and progress - Elicitation within tasks (form and URL modes) - Sampling within tasks - Cancellation support - Custom task stores - HTTP transport example - Testing patterns - Best practices tasks-client.md (Client Guide): - Quick start with poll_task() iterator - Handling input_required status - Elicitation and sampling callbacks - Client as task receiver (advanced) - Client-side task handlers - Error handling patterns - Complete working examples

- Update TaskSession references to ServerTaskContext - Update task_execution() to run_task() - Fix result.taskSupport.taskId to result.task.taskId

Replace NotImplementedError with pass since task requests are handled earlier by _task_handlers. The catch-all satisfies pyright's exhaustiveness check while making it clear these cases are intentionally handled elsewhere.

felixweinberger · 2025-11-28T16:59:04Z

src/mcp/client/session.py

                    return await responder.respond(types.ClientResult(root=types.EmptyResult()))

+            case _:  # pragma: no cover
+                raise NotImplementedError()


do we need this?

Also yes we do unforunately need a pragma here. it's never hit because the list of types is exhausted, but we need a default case otherwise pyright errors

felixweinberger · 2025-11-28T17:05:26Z

src/mcp/server/session.py

+
        return True

+    def set_task_result_handler(self, handler: ResponseRouter) -> None:


all this does is wrap another function, do we need this? can't we just self.add_response_router directly somewhere

felixweinberger · 2025-11-28T17:06:35Z

src/mcp/server/session.py

+    # =========================================================================
+    # Request builders for task queueing (internal use)
+    # =========================================================================
+    #
+    # These methods build JSON-RPC requests without sending them. They are used
+    # by TaskContext to construct requests that will be queued instead of sent
+    # directly, avoiding code duplication between ServerSession and TaskContext.


can we please remove

felixweinberger · 2025-11-28T17:07:24Z

src/mcp/server/session.py

+            params=params_data,
+        )
+
+    async def send_message(self, message: SessionMessage) -> None:


again just a wrapper, seems kind of redundant

This is needed as there's no way to access _write_stream externally

felixweinberger · 2025-11-28T17:08:07Z

src/mcp/shared/context.py

    meta: RequestParams.Meta | None
    session: SessionT
    lifespan_context: LifespanContextT
+    experimental: Any = field(default=None)  # Set to Experimental instance by Server


this looks a little fishy, should it really be Any or Experimental | None or something?

felixweinberger · 2025-11-28T17:08:30Z

src/mcp/shared/session.py

+        self._response_routers = []
        self._exit_stack = AsyncExitStack()

+    def add_response_router(self, router: ResponseRouter) -> None:


another 1 line wrapper

Hmm what would you recommend instead? I'd rather external code not access private fields and instead provide a way users should use this.

fair, didn't realize it was being passed through elsewhere

felixweinberger · 2025-11-28T17:11:29Z

src/mcp/types.py

+
+    taskId: str | None = None
+    """Deprecated: Use the `tasks/cancel` request instead of this notification for task cancellation."""
+


This looks like the typescript thing we had where we had a deprecated field - I think this needs to be removed?

felixweinberger · 2025-11-28T17:11:51Z

tests/client/test_stdio.py

        Test basic parent-child process cleanup.
        Parent spawns a single child process that writes continuously to a file.
        """
+        return


was this necessary to make coverage pass?

felixweinberger · 2025-11-28T17:12:07Z

tests/client/test_stdio.py

+        return
        # Create temporary files for each process level
        with tempfile.NamedTemporaryFile(mode="w", delete=False) as f1:
            parent_file = f1.name


this looks very strange - why are we returning before a statement

felixweinberger · 2025-11-28T17:13:53Z

mkdocs.yml

      - Low-Level Server: low-level-server.md
      - Authorization: authorization.md
      - Testing: testing.md
+  - Experimental:


looks like we didn't add anything about tasks to the README - should we at least point people to these docs?

- Remove taskId from CancelledNotificationParams (removed in spec PR #1833) - Update requestId docstring with MUST/MUST NOT requirements from spec - Add missing docstrings for TaskMetadata, RelatedTaskMetadata.taskId, and Task.pollInterval to match schema.ts

- Remove set_task_result_handler wrapper method and its test - Remove internal comment block for request builders - Mark add_response_router as experimental in docstring - Add experimental tasks documentation link to README - Add comment explaining why experimental field uses Any type (circular import: mcp.server.__init__ -> fastmcp -> context)

Rename variables in the two demo sections to be more descriptive and avoid reusing the same names, making the example easier to follow.

* Add regression test for stateless request memory cleanup (modelcontextprotocol#1140) * Implement RFC9728 - Support WWW-Authenticate header by MCP client (modelcontextprotocol#1071) * Add streamable HTTP starlette example to Python SDK docs (modelcontextprotocol#1111) * fix markdown error in README in main (modelcontextprotocol#1147) * README - replace code snippets with examples - add lowlevel to snippets (modelcontextprotocol#1150) * README - replace code snippets with examples - streamable http (modelcontextprotocol#1155) * chore: don't allow users to create issues outside the templates (modelcontextprotocol#1163) * Tests(cli): Add coverage for helper functions (modelcontextprotocol#635) * Docs: Update CallToolResult parsing in README (modelcontextprotocol#812) Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> * docs: add pre-commit install guide on CONTRIBUTING.md (modelcontextprotocol#995) Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> * fix flaky fix-test_streamablehttp_client_resumption test (modelcontextprotocol#1166) * README - replace code snippets with examples -- auth examples (modelcontextprotocol#1164) * Support falling back to OIDC metadata for auth (modelcontextprotocol#1061) * Add CODEOWNERS file for sdk (modelcontextprotocol#1169) * fix flaky test test_88_random_error (modelcontextprotocol#1171) * Make sure `RequestId` is not coerced as `int` (modelcontextprotocol#1178) * Fix: Replace threading.Lock with anyio.Lock for Ray deployment compatibility (modelcontextprotocol#1151) * fix: fix OAuth flow request object handling (modelcontextprotocol#1174) * update codeowners group (modelcontextprotocol#1191) * fix: perform auth server metadata discovery fallbacks on any 4xx (modelcontextprotocol#1193) * server: skip duplicate response on CancelledError (modelcontextprotocol#1153) Co-authored-by: ihrpr <inna@anthropic.com> * Unpack settings in FastMCP (modelcontextprotocol#1198) * chore: Remove unused prompt_manager.py file (modelcontextprotocol#1229) Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu> * Improved supported for ProtectedResourceMetadata (modelcontextprotocol#1235) Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com> * chore: Remove unused variable notification_options (modelcontextprotocol#1238) * Improve README around the Context object (modelcontextprotocol#1203) * fix: allow to pass `list[str]` to `token_endpoint_auth_signing_alg_values_supported` (modelcontextprotocol#1226) * Remove strict validation on `response_modes_supported` member of `OAuthMetadata` (modelcontextprotocol#1243) * Add pyright strict mode on the whole project (modelcontextprotocol#1254) * Consistent casing for default headers Accept and Content-Type (modelcontextprotocol#1263) * Update dependencies and fix type issues (modelcontextprotocol#1268) Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> * fix: prevent async generator cleanup errors in StreamableHTTP transport (modelcontextprotocol#1271) Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com> * chore: uncomment .idea/ in .gitignore (modelcontextprotocol#1287) Co-authored-by: Claude <noreply@anthropic.com> * docs: clarify streamable_http_path configuration when mounting servers (modelcontextprotocol#1172) * feat: Add CORS configuration for browser-based MCP clients (modelcontextprotocol#1059) Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> * Added Audio to FastMCP (modelcontextprotocol#1130) * fix: avoid uncessary retries in OAuth authenticated requests (modelcontextprotocol#1206) Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> * Add PATHEXT to default STDIO env vars in windows (modelcontextprotocol#1256) * fix: error too many values to unpack (expected 2) (modelcontextprotocol#1279) Signed-off-by: San Nguyen <vinhsannguyen91@gmail.com> Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * SDK Parity: Avoid Parsing Server Response for non-JsonRPCMessage Requests (modelcontextprotocol#1290) * types: Setting default value for method: Literal (modelcontextprotocol#1292) * changes structured temperature to not deadly (modelcontextprotocol#1328) * Update simple-resource example to use non-deprecated read_resource return type (modelcontextprotocol#1331) Co-authored-by: Claude <noreply@anthropic.com> * docs: Update README to include link to API docs for modelcontextprotocol#1329 (modelcontextprotocol#1330) * Allow ping requests before initialization (modelcontextprotocol#1312) * Python lint: Ruff rules for pylint and code complexity (modelcontextprotocol#525) * Fix context injection for resources and prompts (modelcontextprotocol#1336) * fix(fastmcp): propagate mimeType in resource template list (modelcontextprotocol#1186) Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * fix: allow elicitations accepted without content (modelcontextprotocol#1285) Co-authored-by: Olivier Schiavo <olivier.schiavo@wengo.com> * Use --frozen in pre-commit config (modelcontextprotocol#1375) * Return HTTP 403 for invalid Origin headers (modelcontextprotocol#1353) * Add test for ProtectedResourceMetadataParsing (modelcontextprotocol#1236) Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com> Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Fastmcp logging progress example (modelcontextprotocol#1270) Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * feat: add paginated list decorators for prompts, resources, and tools (modelcontextprotocol#1286) Co-authored-by: Claude <noreply@anthropic.com> * Remove "unconditionally" from conditional description (modelcontextprotocol#1289) * Use streamable-http consistently in examples (modelcontextprotocol#1389) * feat: Add SDK support for SEP-1034 default values in elicitation schemas (modelcontextprotocol#1337) Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Implementation of SEP 973 - Additional metadata + icons support (modelcontextprotocol#1357) * Add error log for client stdio (modelcontextprotocol#924) Co-authored-by: Your Name <youremail@yourdomain.com> Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Accept additional response_types values from OAuth servers (modelcontextprotocol#1323) * Issue 1379 patch - Fix MCP server OAuth not working with Visual Studio Code and others with extra grant_types (modelcontextprotocol#1380) * Add comprehensive Unicode tests for streamable HTTP transport (modelcontextprotocol#1381) * Update Icon.sizes to use string array format (modelcontextprotocol#1411) * Delete CODEOWNERS to eliminate notification overload (modelcontextprotocol#1413) * fix: fix the system message in simple-chatbot example (modelcontextprotocol#1394) * fix: improve misleading warning for progress callback exceptions (modelcontextprotocol#775) * fix: catch and rethrow SSEError during SSE connection establishment (modelcontextprotocol#975) Co-authored-by: zhangchuanhui <zhangchal@digitalchina.com> Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> * Add icons support for ResourceTemplate (modelcontextprotocol#1412) * Add documentation structure (modelcontextprotocol#1425) * Add documentation about testing (modelcontextprotocol#1426) * Improve OAuth protected resource metadata URL construction per RFC 9728 (modelcontextprotocol#1407) * feat: add ability to remove tools (modelcontextprotocol#1322) Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> * Update README to link to Python SDK documentation (modelcontextprotocol#1430) * fix: update CLAUDE.md to remove auto-addition of reviewers. (modelcontextprotocol#1431) * [client] Implement MCP OAuth scope selection and step-up authorization (modelcontextprotocol#1324) * Handles message type Exception in lowlevel/server.py _handle_message function. Mentioned as TODO on line 528. (modelcontextprotocol#786) Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Fix workspace configuration error with structured_output_lowlevel.py (modelcontextprotocol#1471) Co-authored-by: lorenss-m <saeclmusic@gmail.com> * fix: Remove unnecessary constructor from ResourceServerSettings (modelcontextprotocol#1424) Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * feat: add resource annotations support to FastMCP (modelcontextprotocol#1468) * fix: send params as empty object for list methods without cursor (modelcontextprotocol#1453) * fix: Set the Server session initialization state immediately after respond… (modelcontextprotocol#1478) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> * feat: add tool metadata in FastMCP.tool decorator (modelcontextprotocol#1463) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> * Make client examples workspaces to reflect package code (modelcontextprotocol#1466) * Expose RequestParams._meta in ClientSession.call_tool (modelcontextprotocol#1231) Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Allow CallToolResult to be returned directly to support _meta field for OpenAI Apps (modelcontextprotocol#1459) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> * fix: uv CVE-2025-62518 astral-tokio-tar issue GHSA-j5gw-2vrg-8fgx (modelcontextprotocol#1505) * fix: use proper dependency resolution in CI (modelcontextprotocol#1507) * Upgrade GitHub Actions (modelcontextprotocol#1473) * test: use errno.ENOENT for command not found assertion (modelcontextprotocol#1498) * Replace deprecated dev-dependencies with dependency-groups (modelcontextprotocol#1488) Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * update uv to 0.9.5 (modelcontextprotocol#1510) * Relax Accept header requirement for JSON-only responses (modelcontextprotocol#1500) * fix: replace deprecated dev-dependencies in examples/clients (modelcontextprotocol#1518) * fix: Update spec links to new modelcontextprotocol.io location (modelcontextprotocol#1491) * fix: Replace fixed sleep with active server readiness check in SSE tests (modelcontextprotocol#1526) * fix: Replace arbitrary sleeps with active server readiness checks in tests (modelcontextprotocol#1527) Co-authored-by: Claude <noreply@anthropic.com> * Fix flaky timeout test in test_88_random_error (modelcontextprotocol#1525) * fix: Replace remaining manual server polling with wait_for_server helper (modelcontextprotocol#1529) * Implement RFC 7523 JWT flows (modelcontextprotocol#1247) Co-authored-by: Yann Jouanin <yann.jouanin@valueandco.com> * Fix pyright error and replace wildcard import with explicit imports (modelcontextprotocol#1532) * Fix auth client example URL handling for oauth provider (modelcontextprotocol#1549) * docs: use article "an" before "MCP" instead of "a" (modelcontextprotocol#1558) * Update Starlette to 0.49.1 in uv.lock (modelcontextprotocol#1559) * Fix typo in `ClientSessionGroup` doc string (modelcontextprotocol#1572) * Implement SEP-985: OAuth Protected Resource Metadata discovery fallback (modelcontextprotocol#1548) Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Paul Carleton <paulc@anthropic.com> * Add --frozen flag to uv run commands in Claude config (modelcontextprotocol#1583) * Add get_server_capabilities() to ClientSession (modelcontextprotocol#1588) * Add everything-server for comprehensive MCP conformance testing (modelcontextprotocol#1587) * Get baseline 100% clean coverage (modelcontextprotocol#1553) * Add end-of-file-fixer pre-commit hook (modelcontextprotocol#1610) * Add coverage baseline commit to git-blame-ignore (modelcontextprotocol#1613) * Add SEP-1034 conformance test support to everything-server (modelcontextprotocol#1604) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> * refactor: extract OAuth helper functions and simplify provider state (modelcontextprotocol#1586) * Add client_id_metadata_document_supported to OAuthMetadata (modelcontextprotocol#1603) * Fix OAuth discovery fallback and URL ordering (modelcontextprotocol#1624) * Refactor `func_metadata()` implementation (modelcontextprotocol#1496) * Fix CI highest resolution test to actually test highest versions (modelcontextprotocol#1609) * feat: Pass through and expose additional parameters in `ClientSessionGroup.call_tool` and `.connect_to_server` (modelcontextprotocol#1576) * fix get_client_metadata_scopes on 401 (modelcontextprotocol#1631) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> * chore: Lazy import `jsonschema` library (modelcontextprotocol#1596) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> * docs: Update examples to use stateless HTTP with JSON responses (modelcontextprotocol#1499) * Add tests for JSON Schema 2020-12 field preservation (SEP-1613) (modelcontextprotocol#1649) * Add client_secret_basic authentication support (modelcontextprotocol#1334) Co-authored-by: Paul Carleton <paulc@anthropic.com> * Implement SEP-1577 - Sampling With Tools (modelcontextprotocol#1594) Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Claude <noreply@anthropic.com> * SEP-1330: Elicitation Enum Schema Improvements and Standards Compliance (modelcontextprotocol#1246) Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu> Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * [auth][conformance] add conformance auth client (modelcontextprotocol#1640) Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Implement SEP-986: Tool name validation (modelcontextprotocol#1655) * fix: url for spec (modelcontextprotocol#1659) * feat: implement SEP-991 URL-based client ID (CIMD) support (modelcontextprotocol#1652) Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * Update doc string on custom_route (modelcontextprotocol#1660) * Implement SEP-1036: URL mode elicitation for secure out-of-band interactions (modelcontextprotocol#1580) Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> * Skip empty SSE data to avoid parsing errors (modelcontextprotocol#1670) * SEP-1686: Tasks (modelcontextprotocol#1645) * Add on_session_created callback option (modelcontextprotocol#1710) * Add SSE polling support (SEP-1699) (modelcontextprotocol#1654) * Support client_credentials flow with JWT and Basic auth (modelcontextprotocol#1663) Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> * feat: backwards-compatible create_message overloads for SEP-1577 (modelcontextprotocol#1713) * Merge commit from fork * Auto-enable DNS rebinding protection for localhost servers When a FastMCP server is created with host="127.0.0.1" or "localhost" and no explicit transport_security is provided, automatically enable DNS rebinding protection. Both 127.0.0.1 and localhost are allowed as valid hosts/origins since clients may use either to connect. * Add tests for auto DNS rebinding protection on localhost Tests verify that: - Protection auto-enables for host=127.0.0.1 - Protection auto-enables for host=localhost - Both 127.0.0.1 and localhost are in allowed hosts/origins - Protection does NOT auto-enable for other hosts (e.g., 0.0.0.0) - Explicit transport_security settings are not overridden * Add IPv6 localhost (::1) support for DNS rebinding protection Extend auto-enable DNS rebinding protection to also cover IPv6 localhost. When host="::1", protection is now auto-enabled with appropriate allowed hosts ([::1]:*) and origins (http://[::1]:*). * Fix import ordering in test file * chore: update LATEST_PROTOCOL_VERSION to 2025-11-25 (modelcontextprotocol#1715) * fix: add lifespan context manager to StreamableHTTP mounting examples (modelcontextprotocol#1669) Co-authored-by: TheMailmans <tyler@example.com> Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> * fix: handle ClosedResourceError in StreamableHTTP message router (modelcontextprotocol#1384) Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> * fix: skip priming events and close_sse_stream for old protocol versions (modelcontextprotocol#1719) * refactor(auth): remove unused _register_client method (modelcontextprotocol#1748) * [MCP-266] Add tests for Gumloop server extensions * Fix uv workspace config for gumloop-mcp package name * Sync with upstream MCP SDK and fix merge conflicts * Fix tool cache timing and missing properties check in server.py * Fix coverage and add proper type annotations for Gumloop extensions * Version up * Skip README code example tests (Gumloop README has no code snippets) * Support gumloop and mcp outptuschema * Add publish tools to dev dependencies and update README for uv --------- Signed-off-by: San Nguyen <vinhsannguyen91@gmail.com> Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com> Co-authored-by: yurikunash <143175350+yurikunash@users.noreply.github.com> Co-authored-by: Pamela Fox <pamela.fox@gmail.com> Co-authored-by: Inna Harper <inna.hrpr@gmail.com> Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com> Co-authored-by: Ian Davenport <49379192+davenpi@users.noreply.github.com> Co-authored-by: Dagang Wei <functicons@gmail.com> Co-authored-by: Felix Weinberger <fweinberger@anthropic.com> Co-authored-by: Stanley Law <stanleylkal@gmail.com> Co-authored-by: Luca Chang <131398524+LucaButBoring@users.noreply.github.com> Co-authored-by: leweng <leweng@nvidia.com> Co-authored-by: Clare Liguori <liguori@amazon.com> Co-authored-by: lukacf <luka@peltarion.com> Co-authored-by: ihrpr <inna@anthropic.com> Co-authored-by: Tapan Chugh <chugh.tapan@gmail.com> Co-authored-by: Tapan Chugh <tapanc@cs.washington.edu> Co-authored-by: Yann Jouanin <4557670+yannj-fr@users.noreply.github.com> Co-authored-by: Paul Carleton <paulcarletonjr@gmail.com> Co-authored-by: Sreenath Somarajapuram <somarajapuram@gmail.com> Co-authored-by: Omer Korner <omerkorner@gmail.com> Co-authored-by: joesavage-silabs <159480754+joesavage-silabs@users.noreply.github.com> Co-authored-by: Gregory L <gregory.linford@mistral.ai> Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com> Co-authored-by: Moustapha Ebnou <155577789+mous222@users.noreply.github.com> Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Jerome <jerome@anthropic.com> Co-authored-by: xavier <84836280+dragonier23@users.noreply.github.com> Co-authored-by: keurcien <keurcien.luu@gmail.com> Co-authored-by: Tim Esler <tim.esler@gmail.com> Co-authored-by: San Nguyen <22189661+sandangel@users.noreply.github.com> Co-authored-by: Justin Wang <89049861+justin-yi-wang@users.noreply.github.com> Co-authored-by: jess <jessachandler@gmail.com> Co-authored-by: Peter Alexander <pja@anthropic.com> Co-authored-by: Reid Geyer <12072650+reidg44@users.noreply.github.com> Co-authored-by: Eleftheria Stein-Kousathana <eleftheria.kousathana@gmail.com> Co-authored-by: Christian Clauss <cclauss@me.com> Co-authored-by: pchoudhury22 <pchoudhury22@apple.com> Co-authored-by: owengo <owengo@users.noreply.github.com> Co-authored-by: Olivier Schiavo <olivier.schiavo@wengo.com> Co-authored-by: Steve Billings <billings.steve@gmail.com> Co-authored-by: Mike Salvatore <mike.s.salvatore@gmail.com> Co-authored-by: pengwa <pengwa@microsoft.com> Co-authored-by: Your Name <youremail@yourdomain.com> Co-authored-by: Jon Shea <jonshea@jonshea.com> Co-authored-by: automaton82 <terrence.sheflin@gmail.com> Co-authored-by: Yukuan Jia <jiayukuan@huawei.com> Co-authored-by: Lorenzo <lorenzo_cesconeto@hotmail.com> Co-authored-by: ZhangChuanhui <57099533+zhangch-ss@users.noreply.github.com> Co-authored-by: zhangchuanhui <zhangchal@digitalchina.com> Co-authored-by: Marcus Shu <46469249+shulkx@users.noreply.github.com> Co-authored-by: Brandon Wu <49291449+brandonspark@users.noreply.github.com> Co-authored-by: Dogacan Colak <dogacancolak@gmail.com> Co-authored-by: AishwaryaKalloli <30429206+AishwaryaKalloli@users.noreply.github.com> Co-authored-by: lorenss-m <saeclmusic@gmail.com> Co-authored-by: Rocky Haotian Du <2712479005@qq.com> Co-authored-by: Fenn Bailey <fennb@users.noreply.github.com> Co-authored-by: daamitt <147169947+daamitt@users.noreply.github.com> Co-authored-by: Mat Leonard <137834585+mat-octave@users.noreply.github.com> Co-authored-by: Samuel Felipe Chenatti <samuel.chenatti@gmail.com> Co-authored-by: Brandon Shar <6599653+BrandonShar@users.noreply.github.com> Co-authored-by: mingo007 <maoqiming1@huawei.com> Co-authored-by: adam jones <domdomegg+git@gmail.com> Co-authored-by: Yann Jouanin <yann.jouanin@valueandco.com> Co-authored-by: Koichi ITO <koic.ito@gmail.com> Co-authored-by: Cole Murray <colemurray.cs@gmail.com> Co-authored-by: inaku <63503085+inaku-Gyan@users.noreply.github.com> Co-authored-by: Chris Coutinho <12901868+cbcoutinho@users.noreply.github.com> Co-authored-by: Paul Carleton <paulc@anthropic.com> Co-authored-by: Camila Rondinini <camila@anthropic.com> Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com> Co-authored-by: Andrii Blyzniuk <bliznyuk.andrey@gmail.com> Co-authored-by: Liang Wu <18244712+wuliang229@users.noreply.github.com> Co-authored-by: adam jones <adamj+git@anthropic.com> Co-authored-by: Olivier Chafik <ochafik@anthropic.com> Co-authored-by: Tyler Mailman <themailmaninbox@gmail.com> Co-authored-by: TheMailmans <tyler@example.com> Co-authored-by: Edison <Edison.A.N@hotmail.com> Co-authored-by: dvlpjrs <dvlp.jrs@gmail.com>

felixweinberger linked an issue Nov 20, 2025 that may be closed by this pull request

Implement SEP-1686: Tasks #1546

Closed

felixweinberger removed a link to an issue Nov 20, 2025

Implement SEP-1686: Tasks #1546

Closed

maxisbey changed the title ~~SEP-1686: Tasks MCP~~ SEP-1686: Tasks Nov 20, 2025

maxisbey force-pushed the maxisbey/SEP-1686_Tasks branch from cdf6aa0 to 9bd2aa8 Compare November 20, 2025 19:09

LucaButBoring mentioned this pull request Nov 20, 2025

SEP-1686: Tasks #1554

Closed

9 tasks

chrisguidry mentioned this pull request Nov 21, 2025

Migrate to SDK task protocol types jlowin/fastmcp#2469

Merged

felixweinberger mentioned this pull request Nov 21, 2025

feat: add experimental namespace for URL elicitation modelcontextprotocol/typescript-sdk#1153

Closed

3 tasks

maxisbey force-pushed the maxisbey/SEP-1686_Tasks branch 2 times, most recently from 6c8c071 to 8460a5f Compare November 25, 2025 10:44

maxisbey marked this pull request as ready for review November 25, 2025 10:44

maxisbey requested a review from felixweinberger November 25, 2025 10:44

felixweinberger reviewed Nov 25, 2025

View reviewed changes

src/mcp/types.py Show resolved Hide resolved

felixweinberger linked an issue Nov 25, 2025 that may be closed by this pull request

Implement SEP-1686: Tasks #1546

Closed

jeromevdl mentioned this pull request Nov 26, 2025

[FEATURE] Support MCP Tasks (SEP-1686) with MCPClient strands-agents/sdk-python#1260

Open

felixweinberger reviewed Nov 26, 2025

View reviewed changes

src/mcp/server/lowlevel/server.py Outdated Show resolved Hide resolved

maxisbey added 14 commits November 26, 2025 14:22

update types.py for tasks

2f23ceb

add mvp for server side tasks

7105d9d

tasks additions

2588391

client

109920e

taskhint gone

f75029f

add task helpers to context

aff2a8c

fix utc datetime import, circular dependency, and add type hints

d2968a9

notifications and client side

61354eb

Add initial basic docs

0c7df11

maxisbey and others added 16 commits November 28, 2025 10:09

Revert unnecessary refactor of pkg_version function

a9548e8

Add explanatory comment for type narrowing guard in _handle_response

a28a650

Refactor example servers to have simpler tool dispatch

e68f821

Extract tool-specific logic into separate handler functions, keeping the call_tool decorator handler simple - it just dispatches based on tool name and returns an error for unknown tools.

Merge branch 'main' into maxisbey/SEP-1686_Tasks

fc60097

Fix outdated references in example READMEs

757df38

- Update TaskSession references to ServerTaskContext - Update task_execution() to run_task() - Fix result.taskSupport.taskId to result.task.taskId

Simplify catch-all case in client session match

1688c6a

Replace NotImplementedError with pass since task requests are handled earlier by _task_handlers. The catch-all satisfies pyright's exhaustiveness check while making it clear these cases are intentionally handled elsewhere.

Mark unreachable catch-all case as excluded from coverage

31b5aa1

felixweinberger requested changes Nov 28, 2025

View reviewed changes

maxisbey added 2 commits November 28, 2025 18:05

Re-enable disabled stdio cleanup tests

973641c

felixweinberger previously approved these changes Nov 28, 2025

View reviewed changes

maxisbey dismissed felixweinberger’s stale review via bbd0ed3 November 28, 2025 18:37

Use distinct variable names in interactive task client example

728c139

Rename variables in the two demo sections to be more descriptive and avoid reusing the same names, making the example easier to follow.

maxisbey enabled auto-merge (squash) November 28, 2025 18:51

felixweinberger approved these changes Nov 28, 2025

View reviewed changes

maxisbey merged commit c92bb2f into main Nov 28, 2025
21 checks passed

maxisbey deleted the maxisbey/SEP-1686_Tasks branch November 28, 2025 18:51

marvin-context-protocol bot mentioned this pull request Dec 3, 2025

Make fastapi.cli a runnable package jlowin/fastmcp#2532

Merged

6 tasks


		return True

		def set_task_result_handler(self, handler: ResponseRouter) -> None:


		taskId: str \| None = None
		"""Deprecated: Use the `tasks/cancel` request instead of this notification for task cancellation."""

Conversation

maxisbey commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SEP-1686: Tasks Implementation

Summary

Key Features

Implementation Details

Core Components

Task Lifecycle

Validation

Testing

Documentation

Examples

Breaking Changes

Types of changes

Checklist

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maxisbey commented Nov 19, 2025 •

edited

Loading