Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
status: proposed
contact: baywet
date: 2026-11-10
deciders: [baywet, westey-m]
informed: [rhurey]
---

# Separate MCP discovery consent from tool invocation approval

## Context and Problem Statement

An approval-gated declarative MCP action needs the current tool definition before
it can bind an invocation approval to that definition. Obtaining the definition
is itself a network operation using the configured endpoint and transport
settings. Approval to invoke a tool and permission to contact its server are
different decisions.

The executor cannot determine whether discovery will carry credentials merely by
checking workflow headers: managed connections, custom handlers, and configured
HTTP clients may also supply them. Workflow expressions can change while an
approval is pending, and headers must not become durable checkpoint state.

## Decision Drivers

- Obtain consent before contacting a server for an approval-gated action.
- Bind each consent to its captured destination, workflow headers, and connection reference.
- Require invocation approval after discovering the current published definition.
- Preserve request isolation, replay handling, and credential nonpersistence.
- Support custom handlers and all supported .NET targets.

## Considered Options

- Discover with configured transport settings before requesting tool approval.
Good: one approval interaction and discovery works with authenticated servers.
Neutral: metadata discovery remains a separate handler invocation.
Bad: discovery contacts the destination before any consent.
- Discover without workflow headers before requesting tool approval.
Good: explicit workflow headers are not sent during discovery.
Neutral: the executor still performs a network operation before consent.
Bad: authenticated discovery can fail, and other credential sources remain.
- Obtain discovery consent, then obtain a definition-bound invocation approval.
Good: no handler invocation occurs before discovery consent, including when
authentication is supplied outside workflow headers.
Neutral: discovery and invocation remain separate, invocation-owned MCP calls.
Bad: approval-gated tool calls require two interactions rather than one.

## Decision Outcome

Chosen option: "Obtain discovery consent, then obtain a definition-bound invocation
approval", because it does not depend on the executor detecting every possible
credential source.

For approval-gated actions, the initial request authorizes `tools/list` against
the displayed destination using the configured transport settings. The destination,
workflow headers, and connection reference are captured; host-managed transport
credentials remain subject to the handler's lifecycle. Discovery consent does not
authorize the requested tool invocation. After consent, discovery produces a
separate approval for the captured tool name and arguments. That approval includes
a fingerprint of the complete published tool definition in its internal snapshot.
Before invocation, the executor discovers the definition again and requests fresh
invocation approval if it differs or the previous snapshot lacks a fingerprint.
Changed metadata does not authorize an invocation.

The reserved `tools/list` action is discovery itself: its single approval
authorizes that operation, without requiring it to appear in the tool catalog.
Actions without approval retain their existing direct-invocation behavior.

Each stage uses a distinct request identifier. Responses use captured invocation
parameters rather than reevaluating them. Headers remain in memory only. Approval
snapshots include a keyed fingerprint of captured workflow headers, but neither
the header values nor the key are persisted. Hosts can provide a stable,
cryptographically random key of at least 32 bytes to support cross-process
restoration. When omitted, a process-local key is used; a checkpoint cannot be
resumed after that key is lost. After restoration, changed headers require fresh
discovery consent, while a missing or changed fingerprint key fails closed until
the original key is restored. Older snapshots without a header fingerprint
restart discovery approval. Denied or consumed requests cannot authorize a later
stage.

Handlers must return structured `tools/list` output containing complete protocol
tool definitions, including annotations and metadata. Object properties are
compared in ordinally sorted order recursively; array order and scalar values are
preserved. Missing or ambiguous definitions stop the action rather than bypassing
approval. This compares published metadata, not server implementation identity,
and does not eliminate the interval between discovery and invocation.

Existing approval UIs must handle the additional discovery request and its
notice. When an `ExternalInputRequest` is delivered through `WorkflowSession`,
informational text accompanying its inner approval content is preserved in
delivery order. Older snapshots without discovery consent restart discovery
approval. The ADR remains proposed pending the listed deciders' PR review.
Original file line number Diff line number Diff line change
Expand Up @@ -350,22 +350,7 @@ private static string SerializeToolsList(IEnumerable<Tool> tools)

foreach (Tool tool in tools)
{
writer.WriteStartObject();
writer.WriteString("name", tool.Name);
writer.WriteString("description", tool.Description);
writer.WritePropertyName("inputSchema");
tool.InputSchema.WriteTo(writer);
writer.WritePropertyName("outputSchema");
if (tool.OutputSchema is JsonElement outputSchema)
{
outputSchema.WriteTo(writer);
}
else
{
writer.WriteNullValue();
}

writer.WriteEndObject();
JsonSerializer.Serialize(writer, tool, McpJsonUtilities.DefaultOptions.GetTypeInfo<Tool>());
}

writer.WriteEndArray();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ namespace Microsoft.Agents.AI.Workflows.Declarative;
/// </summary>
public sealed class DeclarativeWorkflowOptions(ResponseAgentProvider agentProvider)
{
private readonly byte[]? _mcpApprovalHeaderFingerprintKey;

/// <summary>
/// Defines the agent provider.
/// </summary>
Expand All @@ -27,6 +29,29 @@ public sealed class DeclarativeWorkflowOptions(ResponseAgentProvider agentProvid
/// </summary>
public IMcpToolHandler? McpToolHandler { get; init; }

/// <summary>
/// Gets or sets the key used to bind pending MCP approvals to their transport headers.
/// </summary>
/// <remarks>
/// Provide a cryptographically random key of at least 32 bytes and retain it across
/// workflow reconstruction to resume pending approvals across processes. When omitted,
/// a process-local key is used; approvals requiring headers cannot resume after that
/// key is lost. The key is copied and is not included in workflow checkpoints.
/// </remarks>
public ReadOnlyMemory<byte>? McpApprovalHeaderFingerprintKey
{
get => this._mcpApprovalHeaderFingerprintKey is null ? null : new ReadOnlyMemory<byte>((byte[])this._mcpApprovalHeaderFingerprintKey.Clone());
init
{
if (value is { } key && key.Length < 32)
{
throw new ArgumentException("The MCP approval header fingerprint key must contain at least 32 bytes.", nameof(value));
}

this._mcpApprovalHeaderFingerprintKey = value?.ToArray();
}
}

/// <summary>
/// Gets or sets the HTTP request handler for executing <c>HttpRequestAction</c> actions within workflows.
/// If not set, HTTP request actions will fail with an appropriate error message.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
// Copyright (c) Microsoft. All rights reserved.

using System.Collections.Generic;
using System.Linq;
using System.Text.Json.Serialization;
using Microsoft.Extensions.AI;

Expand All @@ -9,7 +10,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.Events;
/// <summary>
/// Represents a request for external input.
/// </summary>
public sealed class ExternalInputRequest : IExternalRequestEnvelope
public sealed class ExternalInputRequest : IExternalRequestEnvelopeWithContext
{
/// <summary>
/// The source message that triggered the request for external input.
Expand Down Expand Up @@ -40,6 +41,24 @@ internal ExternalInputRequest(string text)
/// </remarks>
AIContent? IExternalRequestEnvelope.GetInnerRequestContent() => this.GetInnerRequestContent();

/// <inheritdoc />
IReadOnlyList<TextContent> IExternalRequestEnvelopeWithContext.GetRequestContext()
{
AIContent? inner = this.GetInnerRequestContent();
if (inner is not null)
{
foreach (ChatMessage message in this.AgentResponse.Messages)
{
if (message.Contents.Any(content => ReferenceEquals(content, inner)))
{
return [.. message.Contents.OfType<TextContent>()];
}
}
}

return [];
}

private AIContent? GetInnerRequestContent()
{
IList<ChatMessage>? messages = this.AgentResponse?.Messages;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,11 @@ namespace Microsoft.Agents.AI.Workflows.Declarative;
/// <remarks>
/// This interface allows the MCP tool invocation to be abstracted, enabling
/// different implementations for local development, hosted workflows, and testing scenarios.
/// Implementations used by approval-gated MCP actions must support the reserved <c>tools/list</c> operation
Comment thread
baywet marked this conversation as resolved.
Resolved
/// and return a text output containing a structured tools array with complete published tool definitions,
/// including annotations and metadata. The requested tool must include an <c>inputSchema</c> object whose
/// <c>type</c> is <c>object</c>. Discovery is invoked only after explicit discovery approval; a separate
/// approval binds the tool invocation to its definition. Approval fails closed when the definition cannot be verified.
/// </remarks>
public interface IMcpToolHandler
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,12 @@ protected override void Visit(InvokeMcpTool item)
}

// Entry point to invoke MCP tool - may yield for approval
InvokeMcpToolExecutor action = new(item, this._workflowOptions.McpToolHandler, this._workflowOptions.AgentProvider, this._workflowState);
InvokeMcpToolExecutor action = new(
item,
this._workflowOptions.McpToolHandler,
this._workflowOptions.AgentProvider,
this._workflowState,
this._workflowOptions.McpApprovalHeaderFingerprintKey?.ToArray());
this.ContinueWith(action);

// Transition to post action if no external input is required (no approval needed)
Expand Down
Loading
Loading