Handling Tool Calls
An interactive widget can call tools on your app.
When it does, the Teams client sends your app an htmlwidget/calltool invoke activity.
The SDK gives you a typed handler for these invokes and a typed response shape, so you never parse the raw invoke body.
HTML Widgets are in preview and the API surface may change. HTML Widgets are planned for public preview on 11/16.
The flow
- Your app sends a widget whose HTML calls
tools/callover the MCP Apps protocol. - The Teams client forwards that call to your app as an
htmlwidget/calltoolinvoke. - Your handler inspects the tool name and arguments, does its work, and returns a result.
- The Teams client delivers the result back to the widget, which re-renders.
Registering a handler
Register a handler with the @app.on_widget_call_tool decorator. The activity value is typed, so you get the tool name and arguments directly.
from typing import Any
from microsoft_teams.api import HtmlWidgetCallToolInvokeActivity
from microsoft_teams.api.models.html_widget import (
HtmlWidgetCallToolResponse,
McpUiCallToolResult,
McpUiTextContent,
)
from microsoft_teams.apps import ActivityContext
@app.on_widget_call_tool
async def handle_widget_call_tool(
ctx: ActivityContext[HtmlWidgetCallToolInvokeActivity],
) -> HtmlWidgetCallToolResponse:
tool_name = ctx.activity.value.name
args: dict[str, Any] = ctx.activity.value.arguments or {}
if tool_name == "getTime":
from datetime import datetime, timezone
now = datetime.now(tz=timezone.utc)
result = McpUiCallToolResult(
content=[McpUiTextContent(type="text", text=now.strftime("%H:%M:%S"))],
structured_content={"time": now.isoformat()},
is_error=False,
)
else:
result = McpUiCallToolResult(
content=[McpUiTextContent(type="text", text=f"Unknown tool: {tool_name}")],
is_error=True,
)
return HtmlWidgetCallToolResponse(
response_type="htmlwidget/calltoolresult",
call_tool_result=result,
)
Returning a result
A tool call result carries a list of content blocks, optional structured content the widget can render from, and an isError flag.
Teams currently renders text content; the other MCP content types (image, audio, resource) are defined for forward compatibility.
Return an HtmlWidgetCallToolResponse with response_type set to htmlwidget/calltoolresult and a call_tool_result payload.
The result's content is a list of content blocks; structured_content holds data the widget can render from; is_error signals a failure.
McpUiCallToolResult always serializes all three fields, defaulting to [], {} and False, because an omitted field can reach the widget as null.
Python has no buildCallToolResult equivalent, because McpUiCallToolResult applies those defaults when you construct it, including when a field is None.
result = McpUiCallToolResult(
content=[McpUiTextContent(type="text", text="Refreshed!")],
structured_content={"counter": 1, "lastAction": "refresh"},
is_error=False,
)
return HtmlWidgetCallToolResponse(
response_type="htmlwidget/calltoolresult",
call_tool_result=result,
)
Client-supplied call context
The Teams client adds an __msteams__ entry to the arguments of every call, carrying the mcpUrl and correlationId from the widget payload when they were set. The client overwrites any value the widget supplied, and the SDK passes arguments to your handler untouched. Ignore __msteams__ when you read your tool's arguments, validate the other arguments as untrusted input, never throw from the handler, and do not authorize from activity.from.
There is no separate Python type for the entry. arguments is typed Any, and it is a dict when the widget sent an object.
Read the entry from ctx.activity.value.arguments if you need mcpUrl or correlationId, and strip it before treating the remaining arguments as your tool's input:
raw = ctx.activity.value.arguments
if raw is not None and not isinstance(raw, dict):
return HtmlWidgetCallToolResponse(
response_type="htmlwidget/calltoolresult",
call_tool_result=McpUiCallToolResult(
content=[McpUiTextContent(type="text", text="arguments must be an object")],
is_error=True,
),
)
context = (raw or {}).get("__msteams__", {})
args = {k: v for k, v in (raw or {}).items() if k != "__msteams__"}
correlation_id = context.get("correlationId")
Throttling in large contexts
In large or busy contexts the Teams platform may throttle widget tool calls, so your app can receive fewer htmlwidget/calltool invokes than the widget issued. This throttling happens on the platform before the invoke reaches your app, so there is no error or 429 status for your handler to catch and nothing for the SDK to retry. Design your tool handlers so that a dropped call is not fatal: keep them idempotent, and let the widget reflect its own state rather than assuming every call reaches your app.