[Bug] Azure MCP Server missing required maxTokens field in sampling/createMessage requests

[jason-johnson]

Summary

Azure MCP Server (version 2.0.0-beta.10) sends sampling/createMessage requests without the required maxTokens field, causing validation failures in MCP SDK clients that strictly enforce the MCP specification.

Environment

• Azure MCP Server Version: 2.0.0-beta.10 (from mcr.microsoft.com/azure-sdk/azure-mcp:2.0.0-beta.10)
• MCP SDK Version: 1.25.0 (Python)
• Server Mode: --mode namespace
• Transport: Streamable HTTP

Problem Description

When using namespace-mode tools (e.g., appservice, aks, storage), the Azure MCP Server sends sampling/createMessage requests to the client to help route commands. However, these requests are missing the maxTokens field which is required by the MCP specification.

According to the MCP spec and SDK implementation, CreateMessageRequestParams requires:

• messages: array of messages (required)
• maxTokens: integer (required)

Evidence

1. Validation Error from MCP SDK

Failed to validate request: 16 validation errors for ServerRequest
CreateMessageRequest.params.maxTokens
  Field required [type=missing, input_value={'messages': [{'content':...}]}, input_type=dict]

2. Raw Message That Failed Validation

The Azure MCP Server sends:

{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "content": {
          "type": "text",
          "text": "This is a list of available commands for the appservice server..."
        },
        "role": "assistant"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": 4
}

Note: The maxTokens field is completely absent from params.

3. MCP SDK Field Definition

From mcp/types.py in the Python MCP SDK:

class CreateMessageRequestParams(BaseModel):
    messages: list[SamplingMessage]
    maxTokens: int  # Required field, no default
    # ... other optional fields

4. Verification of SDK Requirement

>>> from mcp.types import CreateMessageRequestParams
>>> field_info = CreateMessageRequestParams.model_fields.get('maxTokens')
>>> print(f'required: {field_info.is_required()}, default: {field_info.default}')
required: True, default: PydanticUndefined

Impact

• Namespace tools (appservice, aks, storage, etc.) fail to discover or execute commands
• The learn=true parameter returns empty command lists []
• Only flat tools (like subscription_list) that don't use sampling work correctly

Expected Behavior

The Azure MCP Server should include maxTokens in all sampling/createMessage requests, for example:

{
  "method": "sampling/createMessage",
  "params": {
    "messages": [...],
    "maxTokens": 4096
  },
  "jsonrpc": "2.0",
  "id": 4
}

Workaround Attempted

We attempted to monkey-patch the MCP SDK's CreateMessageRequestParams to make maxTokens optional with a default value, but Pydantic's internal validation caching prevented runtime patching from taking effect.

Suggested Fix

The Azure MCP Server should include a sensible default value for maxTokens (e.g., 4096) in all sampling/createMessage requests to comply with the MCP specification.

[alzimmermsft]

@stephentoub, I think this may have been perfect timing, doesn't your PR #1501 resolve this?

[stephentoub]

@stephentoub, I think this may have been perfect timing, doesn't your PR #1501 resolve this?

Yes, this should be fixed by #1501.