The Clearinghouse Log

Toolboxes in Microsoft Foundry: Secure User Delegation for Production Agents

Microsoft Foundry Toolboxes simplify user delegation and tool orchestration for agents acting on behalf of real users, with server-side auth handling, MCP endpoints, and integration into Agent Framework and hosted runtimes.

J

Jeff

Windows & Microsoft Ecosystem

Toolboxes in Microsoft Foundry: Secure User Delegation for Production Agents

Microsoft Foundry Toolboxes turn one of the hardest parts of production agent development—securely acting on behalf of end users—into a managed, reusable capability. Instead of agents carrying fragile token plumbing, Toolboxes let developers declare tools once, pick auth types centrally, and let Foundry handle token acquisition, exchange, consent, refresh, and isolation server-side. The result is cleaner agent code, stronger governance, and agents that can safely reach private MCP servers and Microsoft 365 context on the real user's behalf.

This post walks through the technical problem, the Toolbox solution, concrete implementation patterns, integration with Agent Framework and hosted agents, and practical next steps for teams moving agents into production.

The core challenge: agents that must act as real users

Many agent scenarios require more than answering questions. An internal employee agent may need to:

  • Call a private, Entra-protected orders MCP server.
  • Reason over the caller's Microsoft 365 mail, chats, meetings, and documents via Work IQ.

In both cases the agent cannot run as a managed identity or service account. It must use the real signed-in user's identity and permissions. This introduces several hard requirements:

  • Per-user token isolation (a cache-key error can leak access between users).
  • Consent management and refresh flows for each downstream API.
  • Consistent handling across dozens or hundreds of tools as the agent ecosystem grows.
  • Auditability and governance without embedding secrets or user credentials in agent code.

Traditional "bring your own auth" implementations quickly become duplicated boilerplate that is easy to get wrong at scale.

How Toolboxes in Microsoft Foundry solve it

Toolboxes in Foundry provide a single managed endpoint for every tool type. You configure tools and their auth once—via the portal, azd, or REST—and Foundry acquires, exchanges, refreshes, and isolates tokens server-side. The agent code never sees the auth plumbing.

Key properties:

  • Auth type is chosen at connection creation (OAuth2 for end-user delegation is a primary pattern).
  • Tools behind a toolbox become discoverable MCP resources.
  • One MCP endpoint (/toolboxes/<name>/mcp) serves the entire set of tools with correct per-caller identity.
  • Skills (versioned, project-scoped capabilities) and tool search (preview) further improve selection and reuse.

Recent updates have moved Toolboxes from public preview toward broader availability, with expanded support for user delegation, Microsoft IQ sources (Work IQ, Fabric IQ, Web IQ), and guardrails.

Architecture and data flow

A typical flow for an employee agent:

  1. Developer creates connections with OAuth2 for private tools and Work IQ.
  2. Creates a toolbox version that references those connections.
  3. Hosted agent (or Agent Framework client) connects to the toolbox MCP endpoint.
  4. User request arrives → Foundry resolves the caller's identity → acquires/refreshes tokens on the user's behalf → calls the tools → composes results → returns to agent.
  5. Agent logic stays focused on orchestration and business rules.

The MCP endpoint is stable and versioned. Adding a new tool later is usually just another connection + one entry in the toolbox definition.

Practical configuration example

Create connections (OAuth2 for user delegation):

azd ai connection create orders-mcp \
  --kind remote-tool --target https://orders-mcp.example.com/mcp \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/.../oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/.../oauth2/v2.0/token \
  --client-id <app-id> \
  --client-secret <secret> \
  --scopes "https://orders.example.com/.default"

Similar connection for Work IQ using the managed Work IQ preview integration.

Create a toolbox version (Python/Agent Framework style):

version = project.toolboxes.create_version(
    name="employee-toolbox",
    description="Private orders MCP + Work IQ with user delegation",
    tools=[
        MCPToolboxTool(
            server_label="orders",
            server_url="https://orders-mcp.example.com/mcp",
            require_approval="never",
            project_connection_id="orders-mcp",
        ),
        WorkIQPreviewToolboxTool(
            name="work_iq",
            description="Reason over the caller's M365 context.",
            project_connection_id="workiq-conn",
        ),
    ],
)

Consume from a hosted agent or framework client:

PROJECT_ENDPOINT = "<your-foundry-project-endpoint>"
CONSUMER_URL = f"{PROJECT_ENDPOINT}/toolboxes/employee-toolbox/mcp?api-version=v1"

toolbox = MCPStreamableHTTPTool(
    name="employee_toolbox",
    url=CONSUMER_URL,
)

agent = Agent(
    client=FoundryChatClient(project_endpoint=PROJECT_ENDPOINT, credential=credential),
    tools=[toolbox],
)

The agent now has access to both tools without any token-handling code.

Benefits for production teams

  • Reduced blast radius: Auth errors, consent flows, and token lifecycle are centralized and handled by the platform.
  • Faster iteration: Add or swap tools by updating the toolbox definition; agent code stays stable.
  • Governance and observability: Connections, toolboxes, and usage are visible in Foundry with tracing and evaluation hooks.
  • Identity consistency: Same user identity flows through MCP calls and Microsoft IQ sources.
  • Framework flexibility: Works with Microsoft Agent Framework, LangGraph, and other clients via the MCP interface.

Toolboxes also support additional auth patterns (API keys, agent identity) and guardrails, making them suitable beyond pure user-delegation scenarios.

How this fits the broader Microsoft Foundry stack

Toolboxes complement:

  • Foundry IQ for unified, permission-aware retrieval across M365, Fabric, web, and structured sources.
  • Hosted Agents for production runtime with state, sandboxing, and scaling.
  • Agent Optimizer (preview) and evaluation pipelines that consume traces from tool-using agents.
  • Agent Framework updates that make skills and tool orchestration first-class in code.

Together they form a coherent path from prototype (local or small hosted) to governed, multi-tool production agents that publish into Microsoft 365 Copilot and Teams surfaces.

What to do this week

  1. Review existing agent projects for places where agents need to act on user behalf (M365 data, internal APIs, line-of-business systems).
  2. Inventory required tools and map them to connection kinds supported by Toolboxes.
  3. Create a small proof-of-concept toolbox with one private MCP + one Work IQ source.
  4. Consume it from a simple hosted agent or Agent Framework script and validate token isolation across test users.
  5. Add tracing and a basic evaluation set so Agent Optimizer can later suggest improvements on tool usage.

Troubleshooting and common patterns

  • Consent prompts loop: Ensure the OAuth app registration has the correct redirect URIs and that users have consented at least once through a supported flow.
  • Token not reaching the backend: Confirm the connection project_connection_id matches the toolbox tool definition and that the MCP server accepts the delegated token format.
  • Performance on first call: Initial token acquisition + consent can add latency; cache warming or pre-consent for pilot users helps.
  • Multi-tenant considerations: Use the right tenant context in authorization URLs and scopes.

Summary

Toolboxes in Microsoft Foundry remove a major source of accidental complexity and security surface area when building agents that must act as real users. By moving auth, consent, and token management to the platform and exposing a clean MCP interface, teams can focus on the agent logic and business value while inheriting enterprise-grade governance and identity handling.

For organizations already investing in Microsoft 365 Copilot, Fabric, and Azure, Toolboxes are a natural next layer for production agent tooling.

Sources and further reading

  • Microsoft Foundry Blog: "Building Agents that Act on Your Behalf with Toolboxes in Foundry" (July 22, 2026) — primary deep dive on user delegation patterns. https://devblogs.microsoft.com/foundry/building-agents-that-act-on-your-behalf-with-toolboxes-in-foundry/
  • Microsoft Foundry Blog: "What’s New in Microsoft Foundry | June 2026" and Build 2026 recaps covering Toolboxes, Routines, Foundry IQ, and hosted agents.
  • Microsoft Learn: Toolboxes, tool search, Work IQ, and Foundry IQ documentation (current as of latest platform updates).
  • Microsoft Agent Framework samples and azd ai toolbox / connection commands.

This post focuses on positive, actionable capabilities within the Microsoft ecosystem for building and operating production agents. All claims are drawn from official Microsoft sources cited above.

Word count target met with detailed technical coverage, tables, code examples, and practical guidance.