Python: [Feature]: Support for MCP sampling tool

[BrightonKahrs]

Description

Agent Framework should advertise the sampling.tools capability, taking in sampling tools from MCP that enforce a data model through result_type

Example from DevUI run

Code Sample

agent.py (client)

import os

from azure.identity.aio import DefaultAzureCredential
from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework import Agent, MCPStreamableHTTPTool
from dotenv import load_dotenv
from agent_framework.devui import serve

load_dotenv()


credential = DefaultAzureCredential()

client = AzureOpenAIResponsesClient(
    credential=credential,
    project_endpoint=os.environ.get("AZURE_AI_PROJECT_ENDPOINT"),
    deployment_name=os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
)

mcp_tools = MCPStreamableHTTPTool(
    name="recipe-server",
    url="http://localhost:8000/mcp",
    description="Local FastMCP server tools",
    client=client,
)

agent = Agent(
    client=client,
    name="assistant",
    instructions="""
        You are a helpful recipe assistant. Use the generate_recipe tool to create recipes for any dish the user asks about.
        Do not respond with your own knowledge of recipes, always use the generate_recipe tool to get the recipe information.
    """,
    tools=[mcp_tools],
)


if __name__ == "__main__":
    serve(entities=[agent], auto_open=True, port=8090)


main.py (mcp server)

from pydantic import BaseModel
from fastmcp import FastMCP, Context


class Ingredient(BaseModel):
    name: str
    quantity: str
    unit: str


class Recipe(BaseModel):
    name: str
    description: str
    servings: int
    prep_time_minutes: int
    cook_time_minutes: int
    ingredients: list[Ingredient]
    steps: list[str]


mcp = FastMCP("agent-framework-mcp-test")


@mcp.tool()
async def generate_recipe(dish: str, servings: int, ctx: Context) -> Recipe:
    """Generate a structured recipe for a given dish and number of servings using the client's LLM."""
    result = await ctx.sample(
        f"Create a recipe for {dish} that serves {servings}", result_type=Recipe
    )

    if not isinstance(result, Recipe):
        raise ValueError("Expected result to be of type Recipe")

    return result


if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)


OS: Windows 11
AF version: 1.0.0rc3
Language: Python

Language/SDK

Python

[m13v]

MCP sampling is underappreciated as a protocol feature. The big advantage is that the server can request inference from the host's LLM without needing its own API key or model configuration - the host delegates and controls the actual model call.

One practical pattern: wrap Claude Code's headless mode (claude -p) as a sampling backend. This lets any MCP server request completions through the host, and you get the benefit of the host's auth, rate limits, and model selection without duplicating that config in every server.

For the result_type enforcement, structured output parsing at the proxy layer works well - validate the response against the expected schema before returning it to the server, and retry with a corrective prompt if it doesn't match.

[m13v]

We implemented an MCP sampling proxy pattern for Fazm (https://fazm.ai/gh) using Claude Code's headless mode. The tool execution layer that handles MCP tool dispatch is here: https://github.com/m13v/fazm/blob/main/Desktop/Sources/Providers/ChatToolExecutor.swift