Merge branch 'main' into elicitation/expect-server-flag

Author: nbarbettini

docs/docs/develop/build-client.mdx

@@ -738,6 +738,10 @@ async function main() {
   try {
     await mcpClient.connectToServer(process.argv[2]);
     await mcpClient.chatLoop();
+  } catch (e) {
+    console.error("Error:", e);
+    await mcpClient.cleanup();
+    process.exit(1);
   } finally {
     await mcpClient.cleanup();
     process.exit(0);
@@ -842,6 +846,7 @@ If you see:
 - `Tool execution failed`: Verify the tool's required environment variables are set
 - `ANTHROPIC_API_KEY is not set`: Check your .env file and environment variables
 - `TypeError`: Ensure you're using the correct types for tool arguments
+- `BadRequestError`: Ensure you have enough credits to access the Anthropic API
 
 </Tab>
 

docs/specification/draft/basic/transports.mdx

@@ -111,7 +111,7 @@ MCP endpoint.
      at any time in order to avoid holding a long-lived connection. The client
      **SHOULD** then "poll" the SSE stream by attempting to reconnect.
    - If the server does close the _connection_ prior to terminating the _SSE stream_,
-     it **SHOULD** send an SSE event with a standard [`retry`](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-retry-value) field before
+     it **SHOULD** send an SSE event with a standard [`retry`](https://html.spec.whatwg.org/multipage/server-sent-events.html#:~:text=field%20name%20is%20%22retry%22) field before
      closing the connection. The client **MUST** respect the `retry` field,
      waiting the given number of milliseconds before attempting to reconnect.
    - The SSE stream **SHOULD** eventually include a JSON-RPC _response_ for the

docs/specification/draft/basic/utilities/tasks.mdx

@@ -108,15 +108,15 @@ The set of capabilities in `capabilities.tasks.requests` is exhaustive. If a req
 
 ### Tool-Level Negotiation
 
-Tool calls are given special consideration for the purpose of task augmentation. In the result of `tools/list`, tools declare support for tasks via `annotations.taskHint`, which if present can have a value of `"always"`, `"optional"`, or `"never"`.
+Tool calls are given special consideration for the purpose of task augmentation. In the result of `tools/list`, tools declare support for tasks via `execution.task`, which if present can have a value of `"always"`, `"optional"`, or `"never"`.
 
 This is to be interpreted as a fine-grained layer in addition to capabilities, following these rules:
 
-1. If a server's capabilities include `tasks.requests.tools.call: false`, then clients **MUST NOT** attempt to use task augmentation on that server's tools, regardless of the `taskHint` value.
-1. If a server's capabilities include `tasks.requests.tools.call: true`, then clients consider the value of `taskHint`, and handle it accordingly:
-   1. If `taskHint` is not present or `"never"`, clients **MUST NOT** attempt to invoke the tool as a task. Servers **SHOULD** return a `-32601` (Method not found) error if a client attempts to do so. This is the default behavior.
-   1. If `taskHint` is `"optional"`, clients **MAY** invoke the tool as a task or as a normal request.
-   1. If `taskHint` is `"always"`, clients **SHOULD** invoke the tool as a task. Servers **MAY** return a `-32601` (Method not found) error if a client does not attempt to do so.
+1. If a server's capabilities do not include `tasks.requests.tools.call`, then clients **MUST NOT** attempt to use task augmentation on that server's tools, regardless of the `execution.task` value.
+1. If a server's capabilities include `tasks.requests.tools.call`, then clients consider the value of `execution.task`, and handle it accordingly:
+   1. If `execution.task` is not present or `"never"`, clients **MUST NOT** attempt to invoke the tool as a task. Servers **SHOULD** return a `-32601` (Method not found) error if a client attempts to do so. This is the default behavior.
+   1. If `execution.task` is `"optional"`, clients **MAY** invoke the tool as a task or as a normal request.
+   1. If `execution.task` is `"always"`, clients **MUST** invoke the tool as a task. Servers **MUST** return a `-32601` (Method not found) error if a client does not attempt to do so.
 
 ## Protocol Messages
 
@@ -182,10 +182,18 @@ This guidance is non-binding and is provisional logic intended to account for th
 
 ### Getting Tasks
 
+<Note>
+
+In the Streamable HTTP (SSE) transport, clients **MAY** disconnect from an SSE stream opened by the server in response to a `tasks/get` request at any time.
+
+While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](../transports#sending-messages-to-the-server).
+
+</Note>
+
 Requestors poll for task completion by sending [`tasks/get`](/specification/draft/schema#tasks%2Fget) requests.
 Requestors **SHOULD** respect the `pollInterval` provided in responses when determining polling frequency.
 
-Requestors **SHOULD** continue polling until the task reaches a terminal status (`completed`, `failed`, or `cancelled`), or until encountering the [`input_required`](#input-required-status) status.
+Requestors **SHOULD** continue polling until the task reaches a terminal status (`completed`, `failed`, or `cancelled`), or until encountering the [`input_required`](#input-required-status) status. Note that invoking `tasks/result` does not imply that the requestor needs to stop polling - requestors **SHOULD** continue polling the task status via `tasks/get` if they are not actively waiting for `tasks/result` to complete.
 
 **Request:**
 
@@ -219,10 +227,20 @@ Requestors **SHOULD** continue polling until the task reaches a terminal status
 
 ### Retrieving Task Results
 
+<Note>
+
+In the Streamable HTTP (SSE) transport, clients **MAY** disconnect from an SSE stream opened by the server in response to a `tasks/result` request at any time.
+
+While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](../transports#sending-messages-to-the-server).
+
+</Note>
+
 After a task completes the operation result is retrieved via [`tasks/result`](/specification/draft/schema#tasks%2Fresult). This is distinct from the initial `CreateTaskResult` response, which contains only task data. The result structure matches the original request type (e.g., `CallToolResult` for `tools/call`).
 
 To retrieve the result of a completed task, requestors can send a `tasks/result` request:
 
+While `tasks/result` blocks until the task reaches a terminal status, requestors can continue polling via `tasks/get` in parallel if they are not actively blocked waiting for the result, such as if their previous `tasks/result` request failed or was cancelled. This allows requestors to monitor status changes or display progress updates while the task executes, even after invoking `tasks/result`.
+
 **Request:**
 
 ```json
@@ -412,7 +430,9 @@ stateDiagram-v2
 
 With the Streamable HTTP (SSE) transport, servers often close SSE streams after delivering a response message, which can lead to ambiguity regarding the stream used for subsequent task messages.
 
-Implementations have flexibility in how they manage SSE streams during task polling and result retrieval.
+Servers can handle this by enqueueing messages to the client to side-channel task-related messages alongside other responses.
+
+Servers have flexibility in how they manage SSE streams during task polling and result retrieval, and clients **SHOULD** expect messages to be delivered on any SSE stream, including the HTTP GET stream.
 One possible approach is maintaining an SSE stream on `tasks/result` (see notes on the `input_required` status).
 Where possible, servers **SHOULD NOT** upgrade to an SSE stream in response to a `tasks/get` request, as the client has indicated it wishes to poll for a result.
 
@@ -482,19 +502,29 @@ sequenceDiagram
     participant S as Server (Receiver)
     Note over C,S: 1. Task Creation
     C->>S: Request with task field (ttl)
+    activate S
     S->>C: CreateTaskResult (taskId, status: working, ttl, pollInterval)
+    deactivate S
     Note over C,S: 2. Task Polling
     C->>S: tasks/get (taskId)
+    activate S
     S->>C: working
+    deactivate S
     Note over S: Task processing continues...
     C->>S: tasks/get (taskId)
+    activate S
     S->>C: working
+    deactivate S
     Note over S: Task completes
     C->>S: tasks/get (taskId)
+    activate S
     S->>C: completed
+    deactivate S
     Note over C,S: 3. Result Retrieval
     C->>S: tasks/result (taskId)
+    activate S
     S->>C: Result content
+    deactivate S
     Note over C,S: 4. Cleanup
     Note over S: After ttl period from creation, task is cleaned up
 ```
@@ -513,44 +543,61 @@ sequenceDiagram
 
     Note over C,S: Client augments with task
     C->>S: tools/call (ttl: 3600000)
+    activate S
     S->>C: CreateTaskResult (task-123, status: working)
+    deactivate S
 
     Note over LLM,C: Client continues processing other requests<br/>while task executes in background
     LLM->>C: Request other operation
     C->>LLM: Other operation result
 
     Note over C,S: Client polls for status
     C->>S: tasks/get (task-123)
+    activate S
     S->>C: working
+    deactivate S
 
     Note over S: Server needs information from client<br/>Task moves to input_required
 
     Note over C,S: Client polls and discovers input_required
     C->>S: tasks/get (task-123)
+    activate S
     S->>C: input_required
+    deactivate S
 
-    Note over C,S: Client receives input requests
+    Note over C,S: Client opens result stream
     C->>S: tasks/result (task-123)
-    S->>C: elicitation/create (task-123)
+    activate S
+    S->>C: elicitation/create (related-task: task-123)
+    activate C
     C->>U: Prompt user for input
     U->>C: Provide information
-    C->>S: elicitation response (task-123)
+    C->>S: elicitation response (related-task: task-123)
+    deactivate C
+    deactivate S
+
+    Note over C,S: Client closes result stream and resumes polling
 
     Note over S: Task continues processing...<br/>Task moves back to working
 
-    Note over C,S: Client polls again
     C->>S: tasks/get (task-123)
+    activate S
     S->>C: working
+    deactivate S
 
     Note over S: Task completes
 
     Note over C,S: Client polls and discovers completion
     C->>S: tasks/get (task-123)
+    activate S
     S->>C: completed
+    deactivate S
 
     Note over C,S: Client retrieves final results
     C->>S: tasks/result (task-123)
+    activate S
     S->>C: Result content
+    deactivate S
     C->>LLM: Process result
 
     Note over S: Results retained for ttl period from creation
@@ -569,13 +616,17 @@ sequenceDiagram
 
     Note over S,C: Server requests client operation (task-augmented)
     S->>C: sampling/createMessage (ttl: 3600000)
+    activate C
     C->>S: CreateTaskResult (request-789, status: working)
+    deactivate C
 
     Note over S: Server continues processing<br/>while waiting for result
 
     Note over S,C: Server polls for result
     S->>C: tasks/get (request-789)
+    activate C
     C->>S: working
+    deactivate C
 
     Note over C,U: Client may present request to user
     C->>U: Review request
@@ -591,11 +642,15 @@ sequenceDiagram
 
     Note over S,C: Server polls and discovers completion
     S->>C: tasks/get (request-789)
+    activate C
     C->>S: completed
+    deactivate C
 
     Note over S,C: Server retrieves result
     S->>C: tasks/result (request-789)
+    activate C
     C->>S: Result content
+    deactivate C
 
     Note over S: Server continues processing
 
@@ -611,20 +666,26 @@ sequenceDiagram
 
     Note over C,S: 1. Task Creation
     C->>S: tools/call (request ID: 42, ttl: 60000)
+    activate S
     S->>C: CreateTaskResult (task-123, status: working)
+    deactivate S
 
     Note over C,S: 2. Task Processing
     C->>S: tasks/get (task-123)
+    activate S
     S->>C: working
+    deactivate S
 
     Note over C,S: 3. Client Cancellation
     Note over C: User requests cancellation
     C->>S: tasks/cancel (taskId: task-123)
+    activate S
 
     Note over S: Server stops execution (best effort)
     Note over S: Task moves to cancelled status
 
     S->>C: Task (status: cancelled)
+    deactivate S
 
     Note over C: Client receives confirmation