Add support for custom headers in HostedMcpServerTool #7053
Conversation
Introduces a Headers property to HostedMcpServerTool for specifying additional request headers. Updates OpenAIResponsesChatClient to pass these headers when creating MCP tools and adds unit tests to verify header roundtripping.
There was a problem hiding this comment.
Pull Request Overview
This PR adds support for custom HTTP headers in HostedMcpServerTool, enabling users to specify additional request headers when communicating with remote MCP servers.
- Introduces a
Headersproperty of typeIDictionary<string, string>?to theHostedMcpServerToolclass - Updates
OpenAIResponsesChatClientto pass these headers to both variants ofResponseTool.CreateMcpTool() - Adds roundtrip tests to verify the Headers property can be set, retrieved, and cleared
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/HostedMcpServerTool.cs | Adds the nullable Headers property with XML documentation |
| src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs | Passes mcpTool.Headers parameter to both CreateMcpTool overloads (URI-based and connector ID-based) |
| test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Tools/HostedMcpServerToolTests.cs | Adds assertions to verify Headers can be set to a dictionary, retrieved, and reset to null |
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Tools/HostedMcpServerToolTests.cs
Show resolved
Hide resolved
|
@stephentoub any chance I can get an assignee on this one to help with getting it through? This is #7049 with the reverts. |
|
Thanks for your PR @echapmanFromBunnings. We originally pursued this API shape because OpenAI supported headers in the request, while Anthropic only supported passing an auth token. I initially took the broader approach and used a dictionary in Later, OpenAI added support for passing the token in the same way Anthropic does, which suggested to me that there might not be many use cases for headers beyond auth and that we don't need a headers dictionary in the class. For the sake of doing an informed decision, could you share more about what kinds of headers you need to pass to your MCP server? If we bring the headers dictionary back, we need to reconsider if we want to keep |
|
Hi @jozkee Since the MCP server essentially operates as an HTTP client, couldn’t we simply allow these headers to leverage the underlying protocol? In this context, headers are not being used for authentication, so encountering a header should not imply it is solely for that purpose. These are two distinct concerns and should be treated as such. |
| public HostedMcpServerToolApprovalMode? ApprovalMode { get; set; } | ||
|
|
||
| /// <summary> | ||
| /// Gets or sets additional headers to include in requests to the remote MCP server. |
There was a problem hiding this comment.
From the previous version of this:
| /// Gets or sets additional headers to include in requests to the remote MCP server. | |
| /// Gets or sets the HTTP headers that the AI service should use when calling the remote MCP server. |
There was a problem hiding this comment.
Do we want to add <remarks> mentioning that some providers may return an error if both AuthorizationToken and an "authorization" header are specified? This is the case for OpenAI.
$ curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-4o-mini",
"tools": [
{
"type": "mcp",
"server_label": "gh",
"server_url": "https://api.githubcopilot.com/mcp",
"authorization": "github_pat_123",
"headers": { "Authorization": "Bearer github_pat_123" }
}
],
"input": "What tools are available?"
}'{
"error": {
"message": "Cannot specify both 'authorization' parameter and 'Authorization' header.",
"type": "invalid_request_error",
"param": "headers",
"code": null
}
}
| url, | ||
| mcpTool.AuthorizationToken, | ||
| mcpTool.ServerDescription) : | ||
| mcpTool.ServerDescription, mcpTool.Headers) : |
There was a problem hiding this comment.
| mcpTool.ServerDescription, mcpTool.Headers) : | |
| mcpTool.ServerDescription, | |
| mcpTool.Headers) : |
| new McpToolConnectorId(mcpTool.ServerAddress), | ||
| mcpTool.AuthorizationToken, | ||
| mcpTool.ServerDescription); | ||
| mcpTool.ServerDescription, mcpTool.Headers); |
There was a problem hiding this comment.
| mcpTool.ServerDescription, mcpTool.Headers); | |
| mcpTool.ServerDescription, | |
| mcpTool.Headers); |
|
CI errors are about CompatibilitySuppression.xml since we are bringing the property back. I suspect we need to remove them from: cc @joperezr |
Deleted baseline suppressions for the Headers property and its setter in HostedMcpServerTool from CompatibilitySuppressions.xml.
Expanded XML documentation for the Headers property in HostedMcpServerTool to clarify usage and behavior. Minor formatting adjustments in OpenAIResponsesChatClient for MCP tool creation calls.
|
Addressed all PR comments, and added extensive documents on that headers prop @jozkee |
Deleted baseline suppressions for get_Headers and set_Headers members of HostedMcpServerTool across net8.0, net9.0, and netstandard2.0. This likely reflects removal or resolution of related compatibility issues.
…manFromBunnings/extensions into AddHeaderToMcpToolCreation
src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/HostedMcpServerTool.cs
Show resolved
Hide resolved
| /// <para> | ||
| /// The underlying provider may respond with an error if <see cref="AuthorizationToken"/> is set and an Authorization header is included. | ||
| /// </para> |
There was a problem hiding this comment.
If a provider would have problems with that, wouldn't it be better for it to just not send the auth header? Basically say that if AuthorizationToken is set, any Authorization header in Headers may be ignored, or alternatively say that AuthorizationToken may be ignored if Headers contains an Authorization header?
There was a problem hiding this comment.
That said, what's the benefit of having both? If we only had Headers, is that not sufficient? The token can be extracted from an auth header.
It feels awkward having both, like there are two possible sources of truth. (At the same time I understand that for the common case, having the simple AuthorizationToken property is simpler.)
There was a problem hiding this comment.
If we only had Headers, is that not sufficient?
It is sufficient but it still creates friction with Claude and OpenAI Connectors that only support Authorization Tokens. Converting the Authorization HTTP Header implies trimming the "Bearer " prefix.
If a provider would have problems with that, wouldn't it be better for it to just not send the auth header? Basically say that if AuthorizationToken is set, any Authorization header in Headers may be ignored, or alternatively say that AuthorizationToken may be ignored if Headers contains an Authorization header?
That would mean us (MEAI) deciding for users and providers in this behavior. My thinking was that is better to simply rely what was given to us to the provider. If we are going to decide how to handle this in MEAI.OpenAI I would rather choose throwing to signal there's a bug, which aligns with OpenAI's current behavior.
| public HostedMcpServerToolApprovalMode? ApprovalMode { get; set; } | ||
|
|
||
| /// <summary> | ||
| /// Gets or sets the HTTP headers that the AI service could use when calling the remote MCP server. |
There was a problem hiding this comment.
| /// Gets or sets the HTTP headers that the AI service could use when calling the remote MCP server. | |
| /// Gets or sets HTTP headers to include when calling the remote MCP server. |
| mcpTool.AuthorizationToken, | ||
| mcpTool.ServerDescription); | ||
| mcpTool.ServerDescription, | ||
| mcpTool.Headers); |
There was a problem hiding this comment.
We should be validating these with unit tests, ala
.3 participants
Introduces a Headers property to HostedMcpServerTool for specifying additional request headers. Updates OpenAIResponsesChatClient to pass these headers when creating MCP tools and adds unit tests to verify header roundtripping.
Microsoft Reviewers: Open in CodeFlow