Implement SEP-1577 - Sampling With Tools

[ochafik]

Implement types from modelcontextprotocol/modelcontextprotocol#1577 (accepted)

Spec PR: modelcontextprotocol/modelcontextprotocol#1796 (merged, and follow up modelcontextprotocol/modelcontextprotocol#1842 pending review)

cc/ @bhosmer-ant

Add support for tool calling during sampling requests, enabling MCP servers to execute agentic workflows using client LLM capabilities.

modelcontextprotocol/modelcontextprotocol#1577

Key changes:

• Add ToolUseContent type for assistant tool invocation requests
• Add ToolResultContent type for tool execution results
• Add ToolChoice type to control tool usage behavior
• Add UserMessage and AssistantMessage types for role-specific messages
• Extend SamplingMessage to support tool content (backward compatible)
• Add SamplingToolsCapability & SamplingContextCapability
• Update CreateMessageRequestParams with tools and toolChoice fields
• Update CreateMessageResult to support tool use content
• Update StopReason to include "toolUse" value
• Add comprehensive unit tests for all new types

The implementation maintains backward compatibility by keeping SamplingMessage as a flexible BaseModel while adding more specific UserMessage and AssistantMessage types for type-safe tool interactions.

All new types follow existing patterns:

• Use Pydantic V2 BaseModel
• Allow extra fields with ConfigDict(extra="allow")
• Include proper docstrings and field descriptions
• Support optional fields where appropriate

[felixweinberger]

pushed a couple of minor CI fixes

[bhosmer-ant]

Couple minor notes inline, also these less minor ones:

---

1. runtime validations of the spec constraints are missing. some claude notes:

⏺ The validations would go in src/mcp/server/session.py:215-248 in the create_message method. This is where the server sends sampling requests
to the client.

Specifically:

1. Capability check ("MUST throw when tools/toolChoice defined but sampling.tools missing"):

  # Would be added before send_request:
  if (tools or tool_choice) and not self._has_sampling_tools_capability():
      raise McpError("Client does not support sampling tools capability")

3. Content mixing validation ("tool result content blocks MUST NOT contain other content types"):
   Could be validated either:
   - Here when building the request messages
   - Or in a Pydantic validator on SamplingMessage itself

---

2. missing new props in the API. more claude notes:

Note that the create_message method is also missing the new tools and toolChoice parameters entirely — the PR only adds the types but
doesn't wire them into the API method. Let me verify:

⏺ Read(src/mcp/server/session.py)
⎿  Read 50 lines

⏺ This is a gap in the PR: The create_message() method at src/mcp/server/session.py:215 doesn't expose the new tools and toolChoice
parameters. Currently it only passes the old parameters to CreateMessageRequestParams.

To actually use the new feature, developers would have to bypass this helper and construct the request manually.

The PR should probably also update this method to:

  async def create_message(
      self,
      messages: list[types.SamplingMessage],
      *,
      max_tokens: int,
      # ... existing params ...
      tools: list[types.Tool] | None = None,  # NEW
      tool_choice: types.ToolChoice | None = None,  # NEW
  ) -> types.CreateMessageResult:

And add the capability validation there.

[bhosmer-ant]

I don't think we want this as the example of how to use the new multiple content blocks :)

(same comment on other places where this pattern shows up)

[ochafik]

Added a probably controversial content_as_list property + updated various usage places. WDYT? cc/ @felixweinberger

[bhosmer-ant]

Seems fine! The main issue was just dropping array items but a convenience method can't hurt.

[bhosmer-ant]

I think we can just use ContentBlock here?

[ochafik]

Thanks @bhosmer-ant !

missing new props in the API

Fixed

Content mixing validation ("tool result content blocks MUST NOT contain other content types"):

Fixed (+ tested)
(also, incubating TS validation here)

MUST throw when tools/toolChoice defined but sampling.tools missing

Somehow missed David's suggestion / wasn't applied, so technically servers CAN set tools/toolChoice with sampling.tools missing (they just SHOULD NOT).

Edit: David's suggestion was applied, adding the check

[bhosmer-ant]

LGTM!